jamiedavenport/policystack/policystack-instrument

policystack-instrument

Make the policy reflect reality: annotate real data flows at their call sites so the @policystack/vite build scans them into the config. The markers are identity functions — they return their value unchanged and have no runtime effect; the build reads them statically.

The markers (from @policystack/sdk)

• collecting(category, value, labels) — wrap a value at the point it is

stored. labels maps each field to a human label, or Ignore to exclude it (e.g. password: Ignore).

• sharing(key, recipient, value) — wrap an outbound payload at a data

egress edge (the CCPA sell/share signal).

• thirdParty(name, purpose, policyUrl?) — declare a vendor exists; place

next to its initialisation.

• defineCookie(category) — declare a consent category at its use site.

Constraint: category, key, recipient, name and the label map must be string / object literals. Non-literal arguments are skipped by the static scanner (it emits a build diagnostic — they are not silently lost, but no annotation is produced). Never pass a variable.

What counts as an un-annotated flow

The scanner already recognises common cookie/vendor surfaces (document.cookie, js-cookie, cookies-next, react-cookie, server set-cookie, and ~30 known vendor imports) and flags any that are not gated by <ConsentGate>, a consent.has(...) check, or an accept/set helper. Look for, in priority order:

1. Persisted user input / DB writes with no nearby collecting().
2. Outbound requests carrying user data (analytics, CRM, webhooks) with no

sharing() and no thirdParty().

1. Cookie / localStorage writes and tracker <script>/SDK init with no

defineCookie() and not consent-gated.

Procedure

1. Grep the data layer and network calls; list candidate flows.
2. Add the smallest correct marker at each call site, reusing presets where

they fit so labels stay consistent:

• Data categories: DataCategories.AccountInfo, DataCategories.Communications, DataCategories.DeviceInfo, DataCategories.LocationData, DataCategories.PaymentInfo, DataCategories.SessionData, DataCategories.UsageData
• Lawful bases: LegalBases.Consent, LegalBases.Contract, LegalBases.LegalObligation, LegalBases.LegitimateInterests, LegalBases.PublicTask, LegalBases.VitalInterests
• Retention: Retention.AsRequiredByLaw, Retention.NinetyDays, Retention.OneYear, Retention.ThirtyDays, Retention.ThreeYears, Retention.UntilAccountDeletion, Retention.UntilSessionExpiry
• Vendors: Providers.AWS, Providers.Auth0, Providers.Clerk, Providers.Cloudflare, Providers.Datadog, Providers.GoogleAnalytics, Providers.LemonSqueezy, Providers.Loops, Providers.Mixpanel, Providers.Paddle, Providers.PayPal, Providers.Plausible, Providers.PostHog, Providers.Postmark, Providers.Resend, Providers.SendGrid, Providers.Sentry, Providers.Stripe, Providers.Vercel
• Compliance bundles: Compliance.CCPA, Compliance.GDPR, Compliance.UK_GDPR

1. Ensure every newly scanned category has a matching data.context /

cookies.context entry in policystack.ts (the typed config enforces this).

1. Run policystack-audit to confirm the config still validates.