@gradial/aci 0.1.52-rc.40 → 0.1.52-rc.41

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.52-rc.41
+
+### Changed
+
+- Shared edge claims support collection-free external-audience delivery.
+  Personalization requires a recognized issuer marker; signed older cookies
+  remain valid evidence for consent withdrawal.
+
 ## 0.1.52-rc.40
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.52-rc.40` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.52-rc.41` is a pre-1.0 public-surface reset for the ACI
 client SDK. Breaking changes from the old `0.1.x` accidental surface are
 intentional: the root import is framework-neutral, framework runtime behavior is
 behind explicit subpaths, and the first required customer path is React/Next.
@@ -8,7 +8,7 @@ behind explicit subpaths, and the first required customer path is React/Next.
 ## Install
 
 ```bash
-npm install @gradial/aci@0.1.52-rc.40 zod@^4
+npm install @gradial/aci@0.1.52-rc.41 zod@^4
 ```
 
 ## Root Import
@@ -137,13 +137,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.40 init my-site --template next-starter
+npx @gradial/aci@0.1.52-rc.41 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.40 init --list
+npx @gradial/aci@0.1.52-rc.41 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/internal/domain/edge/identity.d.ts

@@ -10,6 +10,47 @@ export declare function signIdentity(rawID: string, key: SigningKey): Promise<st
 export declare function randomIdentity(random?: (length: number) => Uint8Array): string;
 export declare function identityHashHex(namespace: string, value: string): Promise<string>;
 export declare function verifyClaims(value: string, keys: Record<string, string>, now: Date): Promise<Record<string, unknown> | null>;
+export declare function verifyClaimsEvidence(value: string, keys: Record<string, string>, now: Date): Promise<Record<string, unknown> | null>;
+/**
+ * The minting path that signed an aci_claims value: 'aci' claims contain
+ * first-party memberships only; 'edge' claims are the minted first-party ∪
+ * external union and require a matching live b2 receipt on a
+ * provider-enabled release.
+ */
+export type ClaimsIssuer = 'aci' | 'edge';
+/**
+ * Exposes the payload's `iss` marker. Malformed/unknown markers — and
+ * pre-0059 unmarked payloads — yield undefined; since the §6 cutover,
+ * verifyClaims rejects those payloads outright, so a verified payload always
+ * carries a marker. The marker identifies the minting path; it does not
+ * grant membership by itself.
+ */
+export declare function claimsIssuer(payload: Record<string, unknown> | null): ClaimsIssuer | undefined;
+/** audience.MaxClaimsCookieBytes — the hard 1 KiB aci_claims budget. */
+export declare const MAX_CLAIMS_COOKIE_BYTES = 1024;
+/** audience.DefaultClaimsTTL — the 24-hour signed-lifetime ceiling. */
+export declare const DEFAULT_CLAIMS_TTL_SECONDS: number;
+/**
+ * Mint rejection: oversize, a malformed key, or a missing issuer marker.
+ * Callers fail closed on it — the edge never truncates or subsets
+ * memberships to fit (ADR 0059 §2/§3).
+ */
+export declare class ClaimsMintError extends Error {
+    readonly name = "ClaimsMintError";
+}
+/**
+ * Mints one signed aci_claims value: v1.{kid}.{base64url(payload)}.{hmac},
+ * byte-identical to Go's ClaimsIssuer.IssueClaims — payload field order is
+ * aud (omitted when empty), seg (omitted when empty), iat, exp, iss, and the
+ * TTL clamps to the 24-hour ceiling. The exact bytes are pinned against the
+ * Go golden in claims_contract.test.ts. Issuance requires an explicit issuer
+ * marker; the marker identifies the minting path, it does not grant
+ * membership by itself.
+ */
+export declare function issueClaims(memberships: {
+    aud?: string[];
+    seg?: string[];
+}, issuer: ClaimsIssuer, key: SigningKey, now: Date, ttlSeconds?: number): Promise<string>;
 export declare function verifyHMAC(value: string, signature: string, secret: string): Promise<boolean>;
 export declare function hmacSHA256(value: string, secret: string): Promise<string>;
 export declare function base64URLEncode(bytes: Uint8Array): string;

package/dist/internal/domain/edge/identity.js

@@ -149,7 +149,30 @@ function bytesToHex(bytes) {
     return value;
 }
 // ── Claims cookie (aci_claims) ──
+// verifyClaims is the PERSONALIZATION grade: signature, expiry, and the
+// ADR 0059 §6 issuer-marker gate — a claim without a fresh marker is never
+// trusted for membership selection. Existing signed cookies expire by their
+// own TTL; their old contents are not read during the transition.
 export async function verifyClaims(value, keys, now) {
+    const payload = await verifyClaimsAuthenticity(value, keys, now);
+    if (payload === null || claimsIssuer(payload) === undefined)
+        return null;
+    return payload;
+}
+// verifyClaimsEvidence is the EVIDENCE grade (anonymous-experiments REQ-6):
+// signature and expiry WITHOUT the issuer gate. The collector's
+// withdrawal/suppression trigger only needs proof that identity-tier state
+// existed — an authentically signed, unexpired pre-cutover (unmarked) cookie
+// is exactly that proof, and the Go collector accepts it the same way (Go
+// ClaimsVerifier.VerifyClaims has no marker gate). Evidence never feeds
+// membership selection, so the §6 gate does not apply here.
+export async function verifyClaimsEvidence(value, keys, now) {
+    return verifyClaimsAuthenticity(value, keys, now);
+}
+// verifyClaimsAuthenticity is the shared core: envelope, keyed signature,
+// and expiry — no policy gate. Every structural failure degrades to null
+// (never an error), matching Go's no-oracle posture.
+async function verifyClaimsAuthenticity(value, keys, now) {
     const parts = value.trim().split('.');
     if (parts.length !== 4 || parts[0] !== 'v1')
         return null;
@@ -169,6 +192,67 @@ export async function verifyClaims(value, keys, now) {
         return null;
     }
 }
+/**
+ * Exposes the payload's `iss` marker. Malformed/unknown markers — and
+ * pre-0059 unmarked payloads — yield undefined; since the §6 cutover,
+ * verifyClaims rejects those payloads outright, so a verified payload always
+ * carries a marker. The marker identifies the minting path; it does not
+ * grant membership by itself.
+ */
+export function claimsIssuer(payload) {
+    const iss = payload?.iss;
+    return iss === 'aci' || iss === 'edge' ? iss : undefined;
+}
+/** audience.MaxClaimsCookieBytes — the hard 1 KiB aci_claims budget. */
+export const MAX_CLAIMS_COOKIE_BYTES = 1024;
+/** audience.DefaultClaimsTTL — the 24-hour signed-lifetime ceiling. */
+export const DEFAULT_CLAIMS_TTL_SECONDS = 24 * 60 * 60;
+/**
+ * Mint rejection: oversize, a malformed key, or a missing issuer marker.
+ * Callers fail closed on it — the edge never truncates or subsets
+ * memberships to fit (ADR 0059 §2/§3).
+ */
+export class ClaimsMintError extends Error {
+    name = 'ClaimsMintError';
+}
+/**
+ * Mints one signed aci_claims value: v1.{kid}.{base64url(payload)}.{hmac},
+ * byte-identical to Go's ClaimsIssuer.IssueClaims — payload field order is
+ * aud (omitted when empty), seg (omitted when empty), iat, exp, iss, and the
+ * TTL clamps to the 24-hour ceiling. The exact bytes are pinned against the
+ * Go golden in claims_contract.test.ts. Issuance requires an explicit issuer
+ * marker; the marker identifies the minting path, it does not grant
+ * membership by itself.
+ */
+export async function issueClaims(memberships, issuer, key, now, ttlSeconds) {
+    const kid = key.kid.trim();
+    if (!key.secret)
+        throw new ClaimsMintError('claims issuer requires a secret');
+    if (!kid)
+        throw new ClaimsMintError('claims issuer requires a kid');
+    if (kid.includes('.'))
+        throw new ClaimsMintError("claims kid must not contain '.'");
+    if (issuer !== 'aci' && issuer !== 'edge') {
+        throw new ClaimsMintError('claims issuer requires an explicit issuer marker');
+    }
+    const ttl = ttlSeconds === undefined || ttlSeconds <= 0 || ttlSeconds > DEFAULT_CLAIMS_TTL_SECONDS
+        ? DEFAULT_CLAIMS_TTL_SECONDS
+        : Math.floor(ttlSeconds);
+    const iat = Math.floor(now.getTime() / 1000);
+    const body = JSON.stringify({
+        ...(memberships.aud?.length ? { aud: memberships.aud } : {}),
+        ...(memberships.seg?.length ? { seg: memberships.seg } : {}),
+        iat,
+        exp: iat + ttl,
+        iss: issuer,
+    });
+    const encoded = base64URLEncode(encoder.encode(body));
+    const value = `v1.${kid}.${encoded}.${await hmacSHA256(`v1.${kid}.${encoded}`, key.secret)}`;
+    if (encoder.encode(value).byteLength > MAX_CLAIMS_COOKIE_BYTES) {
+        throw new ClaimsMintError(`claims cookie exceeds the ${MAX_CLAIMS_COOKIE_BYTES}-byte budget (aud=${memberships.aud?.length ?? 0} seg=${memberships.seg?.length ?? 0})`);
+    }
+    return value;
+}
 // ── Internal crypto helpers ──
 // verifyHMAC returns a verdict about the signature, which is the only visitor
 // input here: a malformed or wrong signature is `false`. A fault importing the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.52-rc.40",
+  "version": "0.1.52-rc.41",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -160,11 +160,11 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.40",
-    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.40",
-    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.40",
-    "@gradial/aci-cli-linux-x64": "0.1.52-rc.40",
-    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.40",
-    "@gradial/aci-cli-win32-x64": "0.1.52-rc.40"
+    "@gradial/aci-cli-darwin-arm64": "0.1.52-rc.41",
+    "@gradial/aci-cli-darwin-x64": "0.1.52-rc.41",
+    "@gradial/aci-cli-linux-arm64": "0.1.52-rc.41",
+    "@gradial/aci-cli-linux-x64": "0.1.52-rc.41",
+    "@gradial/aci-cli-win32-arm64": "0.1.52-rc.41",
+    "@gradial/aci-cli-win32-x64": "0.1.52-rc.41"
   }
 }