@phosra/gatekeeper 0.1.0

package/dist/trust-list-cache.d.ts

@@ -0,0 +1,23 @@
+/**
+ * TrustListCache fetches /.well-known/ocss/trust-list, verifies it to the OCSS ROOT
+ * via @openchildsafety/ocss verifyDocument (the ONLY verifyDocument call in the gatekeeper — it is
+ * the Trust-List-to-root path), and builds a Resolver. signingKey(keyId) resolves the
+ * router role key the enforcement profile was signed with. The profile itself is
+ * verified by the caller via a DIRECT Ed25519 verify with this resolved key — NEVER
+ * by passing the profile to verifyDocument.
+ */
+export declare class TrustListCache {
+    private opts;
+    private resolver?;
+    constructor(opts: {
+        fetchImpl: typeof fetch;
+        baseUrl: string;
+        trustRootXB64Url: string;
+        now: () => number;
+    });
+    refresh(): Promise<void>;
+    ensure(): Promise<void>;
+    /** Resolve "did:ocss:<slug>#<kid>" to a 32-byte Ed25519 public key from the verified list. */
+    signingKey(keyId: string): Uint8Array;
+}
+//# sourceMappingURL=trust-list-cache.d.ts.map

package/dist/trust-list-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-list-cache.d.ts","sourceRoot":"","sources":["../src/trust-list-cache.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,qBAAa,cAAc;IAGvB,OAAO,CAAC,IAAI;IAFd,OAAO,CAAC,QAAQ,CAAC,CAAW;gBAElB,IAAI,EAAE;QAAE,SAAS,EAAE,OAAO,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,MAAM,CAAA;KAAE;IAGnG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQxB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B,8FAA8F;IAC9F,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;CAItC"}

package/dist/trust-list-cache.js

@@ -0,0 +1,35 @@
+import { verifyDocument, fromVerifiedDocument } from "@openchildsafety/ocss";
+/**
+ * TrustListCache fetches /.well-known/ocss/trust-list, verifies it to the OCSS ROOT
+ * via @openchildsafety/ocss verifyDocument (the ONLY verifyDocument call in the gatekeeper — it is
+ * the Trust-List-to-root path), and builds a Resolver. signingKey(keyId) resolves the
+ * router role key the enforcement profile was signed with. The profile itself is
+ * verified by the caller via a DIRECT Ed25519 verify with this resolved key — NEVER
+ * by passing the profile to verifyDocument.
+ */
+export class TrustListCache {
+    opts;
+    resolver;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async refresh() {
+        const res = await this.opts.fetchImpl(this.opts.baseUrl + "/.well-known/ocss/trust-list", { method: "GET" });
+        if (!res.ok)
+            throw new Error(`@phosra/gatekeeper: trust-list fetch failed (${res.status})`);
+        const signed = (await res.json());
+        const doc = verifyDocument(signed, this.opts.trustRootXB64Url); // verify to ROOT
+        this.resolver = fromVerifiedDocument(doc, this.opts.now);
+    }
+    async ensure() {
+        if (!this.resolver)
+            await this.refresh();
+    }
+    /** Resolve "did:ocss:<slug>#<kid>" to a 32-byte Ed25519 public key from the verified list. */
+    signingKey(keyId) {
+        if (!this.resolver)
+            throw new Error("@phosra/gatekeeper: trust list not loaded");
+        return this.resolver.signingKey(keyId);
+    }
+}
+//# sourceMappingURL=trust-list-cache.js.map

package/dist/trust-list-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-list-cache.js","sourceRoot":"","sources":["../src/trust-list-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAiC,MAAM,uBAAuB,CAAC;AAE5G;;;;;;;GAOG;AACH,MAAM,OAAO,cAAc;IAGf;IAFF,QAAQ,CAAY;IAC5B,YACU,IAA+F;QAA/F,SAAI,GAAJ,IAAI,CAA2F;IACtG,CAAC;IAEJ,KAAK,CAAC,OAAO;QACX,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,8BAA8B,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7G,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QAC5F,MAAM,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAmB,CAAC;QACpD,MAAM,GAAG,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,iBAAiB;QACjF,IAAI,CAAC,QAAQ,GAAG,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IAC3C,CAAC;IAED,8FAA8F;IAC9F,UAAU,CAAC,KAAa;QACtB,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QACjF,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,216 @@
+import type { SenderKey, JWK, Receipt } from "@openchildsafety/ocss";
+export interface RatingMapping {
+    ocssCategory: string;
+    myField: string;
+    vocabulary: "mpaa" | "tv_parental" | "esrb" | "pegi" | "age_band";
+    /** Optional declarative remap from a proprietary code to a standard board code. */
+    codeMap?: Record<string, string>;
+}
+export interface GatekeeperConfig {
+    platformDid: string;
+    platformKeyId: string;
+    /** Ed25519 SenderKey; signs RFC 9421 census requests and §8.3.8 receipts. */
+    gatekeeperSigningKey: SenderKey;
+    /** EC P-256 PRIVATE JWK — OPTIONAL/RESERVED for future sealed content flows.
+     *  NEVER used in the enforcement-profile read/verify path (profiles are
+     *  router-signed, not sealed to this key). NEVER shared. */
+    platformPayloadKeyJwk?: JWK;
+    censusBaseUrl: string;
+    /** Ed25519 root X (base64url-raw); verifies the Trust List to root. */
+    trustRootXB64Url: string;
+    /** High-entropy §9.3(b) bound-resolver label; presenting it IS authentication. */
+    endpointId: string;
+    ratingMappings: RatingMapping[];
+    tlRefreshIntervalMs?: number;
+    pollIntervalMs?: number;
+    /** Injectable for tests/non-default runtimes. */
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    /**
+     * HMAC-SHA256 shared secret used to verify the `X-Phosra-Signature` header on
+     * inbound connect-leg deliveries (the server-to-server `POST { endpoint_id_label }`
+     * that the writer-BFF sends after the connect ceremony completes).
+     *
+     * **Algorithm:** `HMAC-SHA256(secret, rawRequestBody)` → lowercase hex.
+     * Matches the server-side signing in `internal/service/webhook.go` lines 155-157.
+     *
+     * **Required in production.** When set, `handleConnect` rejects any request whose
+     * `X-Phosra-Signature` header is absent or does not match (HTTP 401, fail-closed).
+     * When omitted, no signature check is performed — acceptable in a trusted-network
+     * deployment only; SHOULD NOT be omitted in internet-facing environments.
+     *
+     * The secret is returned once at endpoint-mint time; treat it like an API key.
+     */
+    connectSecret?: string;
+}
+export interface Verdict {
+    decision: "allow" | "warn" | "block";
+    failMode: "block" | "allow";
+    ruleSlug: string;
+    ruleRef: string | null;
+    /**
+     * No-op (resolves undefined) when ruleRef === null (fail-closed).
+     *
+     * INTERVENTION-FIRED GUARDRAIL (§8.3.8 spec-faithfulness):
+     * - "applied"  — the enforcement intervention actually fired (content removed,
+     *   connection blocked, feature disabled, etc.).  MUST NOT be used when the
+     *   platform received the signal but did not perform the intervention.
+     *   A signature proves *provenance*, not enforcement truth.  REQUIRES a
+     *   non-empty `method_class` in the receipt body naming the enforcement
+     *   mechanism (e.g. "dns_block", "platform_gate", "content_removal") — the
+     *   census rejects an "applied" receipt with a blank method_class (§8.3.8
+     *   intervention-fired requirement).
+     * - "degraded" — the platform attempted enforcement but the result was partial
+     *   (e.g. 48-hour NCII deadline missed, feature only partially disabled), or
+     *   enforcement was attempted after the fact.  May carry an empty method_class.
+     * - "refused"  — the platform explicitly declined to enforce (with reason).
+     *   May carry an empty method_class.
+     *
+     * Do NOT pass "applied" unless the intervention visibly and verifiably fired.
+     * The `method_class` in the confirmation body is the mechanism-of-enforcement
+     * attestation; `gk.confirm()` defaults it to "platform_gate" when not specified.
+     */
+    confirm: (state: "applied" | "degraded" | "refused") => Promise<Receipt | undefined>;
+}
+/**
+ * §7.3 per-rule minimum-assurance floors mirrored from registry/ocss-rules.json
+ * and internal/ocss/profile/floors.go.  Used by the gatekeeper's assurance-level
+ * guardrail: a signal whose assurance_level falls below a rule's floor MUST be
+ * treated as insufficient and produce a block verdict, regardless of the compiled
+ * profile decision.
+ *
+ * CANONICAL SOURCE: registry/ocss-rules.json "floor" fields.
+ * Widening / narrowing this set is a §12.4 governance action, never an ad-hoc edit.
+ * Assurance rank: self_declared(0) < parental_declared(1) < estimated(2)
+ *               < document_verified(3) < institution_record(4)
+ *
+ * DRIFT GUARD: HARD_AV_FLOOR_RULES (below) is DERIVED from this map — it
+ * automatically covers any new document_verified-floor entry added here.
+ * Never maintain a separate hardcoded set of "hard AV rules".
+ */
+export declare const RULE_ASSURANCE_FLOORS: Readonly<Record<string, number>>;
+/**
+ * Derived set of rule slugs whose §7.3 assurance floor is document_verified
+ * (rank 3) or higher.  MUST NOT be maintained by hand — derived from
+ * RULE_ASSURANCE_FLOORS so that any new document_verified-floor rule is
+ * automatically covered by the confirm-stage hard-AV guardrail in gatekeeper.ts.
+ *
+ * Exported for testing: tests import from this module (not from gatekeeper.ts)
+ * to verify the derivation invariant.
+ */
+export declare const HARD_AV_FLOOR_RULES: ReadonlySet<string>;
+/**
+ * Map from the wire `assurance_level` string to its §7.2 assurance rank.
+ * Unknown strings rank -1 and satisfy nothing (fail-closed).
+ */
+export declare const ASSURANCE_RANK: Readonly<Record<string, number>>;
+/** The product-side extended category — reads `params`/`rule_ref` from the verified
+ *  document. The @openchildsafety/ocss normative ProfileCategory is NOT extended with these. */
+export interface GatekeeperCategory {
+    category: string;
+    decision: "allow" | "warn" | "block";
+    fail_mode: "open" | "closed";
+    rule_slug: string;
+    statute_mapping_ref?: string;
+    /** json.RawMessage from the census: an object on the wire, but tolerate a string. */
+    params?: string | {
+        family?: string;
+        scale?: string;
+        max_allowed?: number;
+    };
+    /** The opaque per-child rule_ref the §8.3.8 confirm submits. Absent on family-less compile. */
+    rule_ref?: string;
+}
+export interface VerifiedProfile {
+    endpointId: string;
+    document_type: string;
+    ocss_version: string;
+    profile_ref?: string;
+    window: {
+        not_before: string;
+        not_after: string;
+    };
+    categories: GatekeeperCategory[];
+}
+export interface Gatekeeper {
+    refreshTrustList(): Promise<void>;
+    refreshProfile(endpointId?: string): Promise<void>;
+    getCachedProfile(endpointId?: string): VerifiedProfile | undefined;
+    isAllowed(args: {
+        endpointId?: string;
+        category: string;
+        signal?: Record<string, unknown>;
+    }): Verdict;
+    check(category: string, ctx?: Record<string, unknown>): Verdict;
+    /**
+     * Low-level confirm: POST a signed §8.3.8 enforcement-confirmation directly.
+     *
+     * PREFER `verdict.confirm()` returned by `isAllowed()` — it carries the category
+     * in scope and applies the §7.3 assurance guardrail (throwing `AssuranceLevelError`
+     * for HARD-AV rules when state === "applied" without document-verified assurance).
+     *
+     * This method is NOT category-aware: calling `confirm("applied")` directly for
+     * `adult_site_av_required` or `hard_id_verification_escalation` will NOT throw
+     * AssuranceLevelError client-side.  Census-side enforcement is the backstop, but
+     * the defense-in-depth client check is bypassed.  Use this method only when you
+     * hold the ruleRef + envelopeRef from a prior isAllowed() call and need to confirm
+     * in a different callsite (e.g. a background task after enforcement fires async).
+     */
+    confirm(envelopeRef: string, ruleRef: string | null, state: "applied" | "degraded" | "refused", methodClass?: string): Promise<Receipt | undefined>;
+    /** P3 connect callback: receives the writer-BFF-delivered endpoint_id_label
+     *  (S2S POST { endpoint_id_label, state }), persists it as the connected
+     *  endpoint, and activates the PULL path (refreshProfile). NOT the provisioner
+     *  (GC1) and does NOT decrypt (GC3). gk.webhook() PUSH path is deferred (GC7). */
+    handleConnect(req: Request): Promise<Response>;
+    /** P4 report-back (§3.2): normalize nativeValue via the SAME crosswalk isAllowed
+     *  uses, echo-suppress against the cached profile ceiling (EXACT equality), then
+     *  sign a self-contained phosra_platform_proposal and POST /api/v1/proposals.
+     *  Phosra-PRODUCT — NOT vocab.ts, NOT enforcement_result. MUST NOT write a rule. */
+    reportParentChange(change: ReportParentChangeArgs): Promise<ReportParentChangeResult>;
+    destroy(): void;
+}
+export declare class RuleRefRequired extends Error {
+    constructor();
+}
+export interface ReportParentChangeArgs {
+    /** Defaults to connectedEndpointId / cfg.endpointId. */
+    endpointId?: string;
+    ocssCategory: string;
+    nativeValue: string;
+    /** Explicit — no silent default (§5.10). */
+    changeScope: "platform_local" | "family_wide";
+}
+export type ReportParentChangeResult = {
+    proposalId: string;
+    delta_kind?: string;
+} | {
+    suppressed: true;
+};
+/** Thrown when reportParentChange is called for a category with no RatingMapping (C8). */
+export declare class NoRatingMappingError extends Error {
+    constructor(category: string);
+}
+/** Thrown when reportParentChange receives a nativeValue that does not resolve to a
+ *  known crosswalk entry (contentAgeFor returns MAX_ORDINAL). MAX_ORDINAL is safe as a
+ *  CONTENT-AGE in isAllowed (→ block), but MUST NOT be emitted as a proposed ceiling
+ *  (desired_max_allowed === MAX_ORDINAL means "allow everything"). */
+export declare class UnmappedRatingValueError extends Error {
+    constructor(vocabulary: string, nativeValue: string);
+}
+/**
+ * Thrown by the §7.3 assurance-level guardrail when a platform calls
+ * verdict.confirm("applied") for a rule whose registered floor is
+ * `document_verified` (or higher) but the enforcement profile was compiled
+ * from a signal that only carried `parental_declared` assurance.
+ *
+ * Spec-faithfulness invariant: a signature proves PROVENANCE, not age TRUTH.
+ * `parental_declared` proves a parent made a statement; it does NOT prove the
+ * hard age-verification a statute like UT/TX app-store AV requires.  The
+ * platform MUST confirm "degraded" in this case, not "applied".
+ *
+ * Affected rules: `adult_site_av_required`, `hard_id_verification_escalation`.
+ */
+export declare class AssuranceLevelError extends Error {
+    constructor(category: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,104 @@
+/**
+ * §7.3 per-rule minimum-assurance floors mirrored from registry/ocss-rules.json
+ * and internal/ocss/profile/floors.go.  Used by the gatekeeper's assurance-level
+ * guardrail: a signal whose assurance_level falls below a rule's floor MUST be
+ * treated as insufficient and produce a block verdict, regardless of the compiled
+ * profile decision.
+ *
+ * CANONICAL SOURCE: registry/ocss-rules.json "floor" fields.
+ * Widening / narrowing this set is a §12.4 governance action, never an ad-hoc edit.
+ * Assurance rank: self_declared(0) < parental_declared(1) < estimated(2)
+ *               < document_verified(3) < institution_record(4)
+ *
+ * DRIFT GUARD: HARD_AV_FLOOR_RULES (below) is DERIVED from this map — it
+ * automatically covers any new document_verified-floor entry added here.
+ * Never maintain a separate hardcoded set of "hard AV rules".
+ */
+export const RULE_ASSURANCE_FLOORS = {
+    // parental_declared floor (rank 1) — the minimum for most age rules
+    rating_age_gate: 1,
+    age_gate: 1,
+    app_store_age_attestation: 1,
+    os_age_signal_ingest: 1,
+    age_signal_broadcast: 1,
+    social_media_min_age: 1,
+    ai_chatbot_age_assertion: 1,
+    teen_minimum_age_16_gate: 1,
+    age_appropriate_profile_mode: 1,
+    // document_verified floor (rank 3) — hard age-verification statutes
+    // A signature proves provenance, not age truth.  @phosra/gatekeeper MUST
+    // refuse to represent a parental_declared or estimated signal as satisfying
+    // these rules (UT HB 311, TX HB 1181, SCREEN Act, UK OSA Part 5).
+    adult_site_av_required: 3,
+    hard_id_verification_escalation: 3,
+};
+/**
+ * Derived set of rule slugs whose §7.3 assurance floor is document_verified
+ * (rank 3) or higher.  MUST NOT be maintained by hand — derived from
+ * RULE_ASSURANCE_FLOORS so that any new document_verified-floor rule is
+ * automatically covered by the confirm-stage hard-AV guardrail in gatekeeper.ts.
+ *
+ * Exported for testing: tests import from this module (not from gatekeeper.ts)
+ * to verify the derivation invariant.
+ */
+export const HARD_AV_FLOOR_RULES = new Set(Object.entries(RULE_ASSURANCE_FLOORS)
+    .filter(([, rank]) => rank >= 3 /* document_verified is rank 3 — see the rank map below */)
+    .map(([rule]) => rule));
+/**
+ * Map from the wire `assurance_level` string to its §7.2 assurance rank.
+ * Unknown strings rank -1 and satisfy nothing (fail-closed).
+ */
+export const ASSURANCE_RANK = {
+    self_declared: 0,
+    parental_declared: 1,
+    estimated: 2,
+    document_verified: 3,
+    institution_record: 4,
+};
+export class RuleRefRequired extends Error {
+    constructor() {
+        super("§8.3.8: rule_ref is required — refusing to confirm a fail-closed verdict (no rule was enforced)");
+        this.name = "RuleRefRequired";
+    }
+}
+/** Thrown when reportParentChange is called for a category with no RatingMapping (C8). */
+export class NoRatingMappingError extends Error {
+    constructor(category) {
+        super(`reportParentChange: no rating mapping for "${category}" — only declared total-ordered rating fields are reportable (§5.7)`);
+        this.name = "NoRatingMappingError";
+    }
+}
+/** Thrown when reportParentChange receives a nativeValue that does not resolve to a
+ *  known crosswalk entry (contentAgeFor returns MAX_ORDINAL). MAX_ORDINAL is safe as a
+ *  CONTENT-AGE in isAllowed (→ block), but MUST NOT be emitted as a proposed ceiling
+ *  (desired_max_allowed === MAX_ORDINAL means "allow everything"). */
+export class UnmappedRatingValueError extends Error {
+    constructor(vocabulary, nativeValue) {
+        super(`reportParentChange: "${nativeValue}" does not map to a known age in vocabulary "${vocabulary}" — rejecting to avoid emitting a maximally-permissive proposal`);
+        this.name = "UnmappedRatingValueError";
+    }
+}
+/**
+ * Thrown by the §7.3 assurance-level guardrail when a platform calls
+ * verdict.confirm("applied") for a rule whose registered floor is
+ * `document_verified` (or higher) but the enforcement profile was compiled
+ * from a signal that only carried `parental_declared` assurance.
+ *
+ * Spec-faithfulness invariant: a signature proves PROVENANCE, not age TRUTH.
+ * `parental_declared` proves a parent made a statement; it does NOT prove the
+ * hard age-verification a statute like UT/TX app-store AV requires.  The
+ * platform MUST confirm "degraded" in this case, not "applied".
+ *
+ * Affected rules: `adult_site_av_required`, `hard_id_verification_escalation`.
+ */
+export class AssuranceLevelError extends Error {
+    constructor(category) {
+        super(`§7.3 assurance guardrail: "${category}" has a document_verified floor — ` +
+            `confirm("applied") is refused because a parental_declared signal proves provenance, ` +
+            `not the hard age-verification this statute requires. ` +
+            `Confirm "degraded" to honestly attest that enforcement was attempted but the ` +
+            `required assurance level was not met.`);
+        this.name = "AssuranceLevelError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA8EA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAqC;IACrE,oEAAoE;IACpE,eAAe,EAAgB,CAAC;IAChC,QAAQ,EAAuB,CAAC;IAChC,yBAAyB,EAAM,CAAC;IAChC,oBAAoB,EAAW,CAAC;IAChC,oBAAoB,EAAW,CAAC;IAChC,oBAAoB,EAAW,CAAC;IAChC,wBAAwB,EAAO,CAAC;IAChC,wBAAwB,EAAO,CAAC;IAChC,4BAA4B,EAAG,CAAC;IAChC,oEAAoE;IACpE,yEAAyE;IACzE,4EAA4E;IAC5E,kEAAkE;IAClE,sBAAsB,EAAW,CAAC;IAClC,+BAA+B,EAAE,CAAC;CAC1B,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAC7D,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC;KAClC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,0DAA0D,CAAC;KAC1F,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAqC;IAC9D,aAAa,EAAO,CAAC;IACrB,iBAAiB,EAAG,CAAC;IACrB,SAAS,EAAW,CAAC;IACrB,iBAAiB,EAAG,CAAC;IACrB,kBAAkB,EAAE,CAAC;CACb,CAAC;AAgEX,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC;QACE,KAAK,CAAC,iGAAiG,CAAC,CAAC;QACzG,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAeD,0FAA0F;AAC1F,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,QAAgB;QAC1B,KAAK,CAAC,8CAA8C,QAAQ,qEAAqE,CAAC,CAAC;QACnI,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;sEAGsE;AACtE,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD,YAAY,UAAkB,EAAE,WAAmB;QACjD,KAAK,CAAC,wBAAwB,WAAW,gDAAgD,UAAU,iEAAiE,CAAC,CAAC;QACtK,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,QAAgB;QAC1B,KAAK,CACH,8BAA8B,QAAQ,oCAAoC;YAC1E,sFAAsF;YACtF,uDAAuD;YACvD,+EAA+E;YAC/E,uCAAuC,CACxC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@phosra/gatekeeper",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+    "./protocol": { "import": "./dist/protocol.js", "types": "./dist/protocol.d.ts" }
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@openchildsafety/ocss": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "vitest": "^1.6.1",
+    "@phosra/link": "^0.1.0"
+  }
+}