@core / consent

1.1.0 ▾

1.1.0

인증됨MIT

GitHub

GDPR 쿠키 동의: 거부·동의가 동등한 배너, 카테고리, 동의 기록, ConsentGate, Consent Mode v2

코드파일 9개컨텍스트약 743토큰검사 통과

약 743토큰→ src/lib/consent/AGENTS.md→ .cursor/rules/genpm-core-consent.mdc

이것이 AI가 src/lib/consent에서 작업할 때 읽는 내용 그대로입니다. 그 외에는 컨텍스트에 아무것도 추가되지 않습니다.

Purpose

Cookie consent that meets GDPR/ePrivacy: categories (necessary always on; analytics, marketing, preferences off by default), a banner where "Reject all" is as prominent as "Accept all", a preferences center, proof of each decision (consent_records: choices, policy version, date; no IP), server checks (hasConsent), a client ConsentGate and Google Consent Mode v2 values. Changing CONSENT_POLICY_VERSION asks everyone again.

Map

index.ts — server API: getConsent, hasConsent, recordConsent, consentModeDefaultsScript, consentHistory, cookieDomain.
react.ts — client: ConsentBanner, ConsentGate, CookieSettingsButton, openConsentPreferences, readClientConsent, currentPolicyVersion.
adapters/hono.ts — consentRoutes(). adapters/next.ts — consentRoute() → { GET, POST }.

Integration

Env: CONSENT_POLICY_VERSION (bump it when the cookie policy changes), SITE_URL (its host gives the registrable domain where third-party tags set their cookies: the last two labels) and, when that guess is wrong (e.g. .co.uk), CONSENT_COOKIE_DOMAIN=example.co.uk. Migrations as in src/lib/db/AGENTS.md.
Mount /api/consent (pass cookiesByCategory, e.g. { analytics: ['_ga'], marketing: ['_fbp', '_ttp'] }, so withdrawing deletes them, host-only and on the registrable domain). The endpoint only accepts same-origin JSON POSTs (CSRF): a cross-site Origin/Sec-Fetch-Site gets 403 and other content types 415; the banner already posts that way.
Root layout: <ConsentBanner policyVersion={policyVersion()} policyHref="/cookies" labels={translated} /> and in the footer <CookieSettingsButton /> (a button that calls openConsentPreferences()). The banner also renders <meta name="consent-policy-version">: client checks treat a decision made under another version as undecided (everything off) until the visitor decides again.
Wrap every analytics/marketing script: <ConsentGate category="marketing" policyVersion={policyVersion()}>…</ConsentGate> (policyVersion is optional when the banner is on the page); on the server use hasConsent(cookieHeader, 'analytics').
With Google tags, render consentModeDefaultsScript(getConsent(cookieHeader)) inline before them.
Verify (browser devtools): before deciding, no request goes to third-party analytics or ad domains.

Conventions

Labels must be translated (labels prop); keep both main buttons equal in style and size.
The consent cookie is first-party, not HttpOnly (scripts must read it), and holds no personal data.
Keep the cookie policy page listing every cookie per category.

Don't

Don't pre-check categories, use "scroll means consent" or hide "Reject all" behind extra clicks.
Don't load analytics/marketing scripts outside ConsentGate, or send hit data server-side without consent.
Don't block the site behind the banner (cookie walls).

# @core/consent — rules for AI agents

## Purpose
Cookie consent that meets GDPR/ePrivacy: categories (necessary always on; analytics, marketing, preferences off by
default), a banner where "Reject all" is as prominent as "Accept all", a preferences center, proof of each decision
(`consent_records`: choices, policy version, date; no IP), server checks (`hasConsent`), a client `ConsentGate` and
Google Consent Mode v2 values. Changing `CONSENT_POLICY_VERSION` asks everyone again.

## Map
- `index.ts` — server API: `getConsent`, `hasConsent`, `recordConsent`, `consentModeDefaultsScript`, `consentHistory`, `cookieDomain`.
- `react.ts` — client: `ConsentBanner`, `ConsentGate`, `CookieSettingsButton`, `openConsentPreferences`, `readClientConsent`, `currentPolicyVersion`.
- `adapters/hono.ts` — `consentRoutes()`. `adapters/next.ts` — `consentRoute()` → `{ GET, POST }`.

## Integration
1. Env: `CONSENT_POLICY_VERSION` (bump it when the cookie policy changes), `SITE_URL` (its host gives the registrable
   domain where third-party tags set their cookies: the last two labels) and, when that guess is wrong (e.g. `.co.uk`),
   `CONSENT_COOKIE_DOMAIN=example.co.uk`. Migrations as in `src/lib/db/AGENTS.md`.
2. Mount `/api/consent` (pass `cookiesByCategory`, e.g. `{ analytics: ['_ga'], marketing: ['_fbp', '_ttp'] }`, so withdrawing
   deletes them, host-only and on the registrable domain). The endpoint only accepts same-origin JSON POSTs (CSRF):
   a cross-site `Origin`/`Sec-Fetch-Site` gets 403 and other content types 415; the banner already posts that way.
3. Root layout: `<ConsentBanner policyVersion={policyVersion()} policyHref="/cookies" labels={translated} />` and in the footer
   `<CookieSettingsButton />` (a button that calls `openConsentPreferences()`). The banner also renders `<meta name="consent-policy-version">`: client checks
   treat a decision made under another version as undecided (everything off) until the visitor decides again.
4. Wrap every analytics/marketing script: `<ConsentGate category="marketing" policyVersion={policyVersion()}>…</ConsentGate>`
   (`policyVersion` is optional when the banner is on the page); on the server use `hasConsent(cookieHeader, 'analytics')`.
5. With Google tags, render `consentModeDefaultsScript(getConsent(cookieHeader))` inline before them.
6. Verify (browser devtools): before deciding, no request goes to third-party analytics or ad domains.

## Conventions
- Labels must be translated (`labels` prop); keep both main buttons equal in style and size.
- The consent cookie is first-party, not HttpOnly (scripts must read it), and holds no personal data.
- Keep the cookie policy page listing every cookie per category.

## Don't
- Don't pre-check categories, use "scroll means consent" or hide "Reject all" behind extra clicks.
- Don't load analytics/marketing scripts outside `ConsentGate`, or send hit data server-side without consent.
- Don't block the site behind the banner (cookie walls).

.genpmignore 적용 후 주입될 정확한 트리입니다. 고정 대상:

src/lib/consent/schema.ts읽기 전용 · 37d6a8f

// Tablas de @core/consent. Las recoge drizzle-kit vía src/lib/db/drizzle.config.ts.
import { index, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
import { primaryId } from '../db/index.ts';

/** Prueba del consentimiento (RGPD art. 7.1): qué se eligió, con qué versión de la política y cuándo. Sin IP. */
export const consentRecords = pgTable(
  'consent_records',
  {
    id: primaryId('cns'),
    /** Id aleatorio del navegador (en la cookie); no identifica a la persona. */
    subjectId: text('subject_id').notNull(),
    choices: jsonb('choices').$type<Record<string, boolean>>().notNull(),
    policyVersion: text('policy_version').notNull(),
    /** `banner`, `preferences`, `withdraw`. */
    action: text('action').notNull(),
    createdAt: timestamp('created_at', { withTimezone: true, mode: 'date' }).notNull().defaultNow(),
  },
  (t) => [index('consent_records_subject_idx').on(t.subjectId, t.createdAt)],
);