@adonis-agora/flags 0.0.0-beta-20261112141227

package/dist/src/topology/remote_source.d.ts

@@ -0,0 +1,39 @@
+import { type Ruleset } from '@adonis-agora/flags-core';
+import type { RulesetSource, SourceStatus } from '../ruleset_source.js';
+import type { TokenSource } from './token.js';
+export interface RemoteSourceOptions {
+    /** The control-plane base URL (`https://flags.example.com/_flags`). */
+    url: string;
+    token: TokenSource;
+    /** The tenant's partition (sent as `x-flags-tenant`; the token decides what it really is). */
+    partition: string;
+    /**
+     * Local file holding the last ruleset received. Read at boot when the control-plane is
+     * unreachable, so a deploy during an outage still serves real targeting. Default: none.
+     */
+    snapshotPath?: string;
+    /** Use server-sent events for push updates. Default `true`; polling always runs as a fallback. */
+    stream?: boolean;
+    /** Poll interval (ms). Default 30000 with streaming, 5000 without. */
+    intervalMs?: number;
+    /** Advertised capabilities (sent as `x-flags-capabilities`). */
+    capabilities?: string[];
+    fetch?: typeof fetch;
+    onError?: (error: unknown) => void;
+}
+/**
+ * A tenant's ruleset: fetched from the control-plane (conditional GET by ETag), kept fresh by an SSE
+ * stream with polling as a fallback, and snapshotted to disk. Evaluation stays local.
+ */
+export declare class RemoteSource implements RulesetSource {
+    #private;
+    private readonly options;
+    constructor(options: RemoteSourceOptions);
+    start(): Promise<void>;
+    current(): Ruleset;
+    onChange(listener: (ruleset: Ruleset) => void): () => void;
+    refresh(): Promise<boolean>;
+    status(): SourceStatus;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=remote_source.d.ts.map

package/dist/src/topology/remote_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote_source.d.ts","sourceRoot":"","sources":["../../../src/topology/remote_source.ts"],"names":[],"mappings":"AAEA,OAAO,EAAwC,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,WAAW,CAAC;IACnB,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,qBAAa,YAAa,YAAW,aAAa;;IAYpC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,EAAE,mBAAmB,EAExD;IAgBK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3B;IAED,OAAO,IAAI,OAAO,CAEjB;IAED,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAGzD;IAED,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAK1B;IA4FD,MAAM,IAAI,YAAY,CAQrB;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAI1B;CACF"}

package/dist/src/topology/remote_source.js

@@ -0,0 +1,184 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { emptyRuleset, RULESET_SCHEMA_VERSION } from '@adonis-agora/flags-core';
+/**
+ * A tenant's ruleset: fetched from the control-plane (conditional GET by ETag), kept fresh by an SSE
+ * stream with polling as a fallback, and snapshotted to disk. Evaluation stays local.
+ */
+export class RemoteSource {
+    options;
+    #ruleset = emptyRuleset('0');
+    #loadedAt = null;
+    #lastError = null;
+    #listeners = new Set();
+    #timer;
+    #stream;
+    #streaming = false;
+    #stopped = false;
+    #refreshing;
+    #fetch;
+    constructor(options) {
+        this.options = options;
+        this.#fetch = options.fetch ?? fetch;
+    }
+    get #base() {
+        return this.options.url.replace(/\/$/, '');
+    }
+    async #headers() {
+        return {
+            authorization: `Bearer ${await this.options.token.get()}`,
+            'x-flags-tenant': this.options.partition,
+            'x-flags-capabilities': (this.options.capabilities ?? [`ruleset:v${RULESET_SCHEMA_VERSION}`]).join(','),
+        };
+    }
+    async start() {
+        this.#stopped = false;
+        const loaded = await this.refresh();
+        if (!loaded && !this.#loadedAt && this.options.snapshotPath) {
+            try {
+                const snapshot = JSON.parse(await readFile(this.options.snapshotPath, 'utf8'));
+                this.#set(snapshot, false);
+            }
+            catch {
+                // No snapshot yet: serve code defaults until the control-plane answers.
+            }
+        }
+        const streaming = this.options.stream !== false;
+        this.#timer = setInterval(() => void this.refresh(), this.options.intervalMs ?? (streaming ? 30_000 : 5000));
+        this.#timer.unref();
+        if (streaming)
+            void this.#openStream();
+    }
+    current() {
+        return this.#ruleset;
+    }
+    onChange(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    refresh() {
+        this.#refreshing ??= this.#refresh().finally(() => {
+            this.#refreshing = undefined;
+        });
+        return this.#refreshing;
+    }
+    async #refresh() {
+        try {
+            const headers = await this.#headers();
+            if (this.#loadedAt)
+                headers['if-none-match'] = `"${this.#ruleset.version}"`;
+            const response = await this.#fetch(`${this.#base}/v1/ruleset`, { headers });
+            if (response.status === 304) {
+                this.#lastError = null;
+                return false;
+            }
+            if (response.status === 401)
+                this.options.token.invalidate?.();
+            if (!response.ok)
+                throw new Error(`control-plane answered ${response.status}`);
+            const ruleset = (await response.json());
+            if (this.#loadedAt && ruleset.version === this.#ruleset.version)
+                return false;
+            this.#set(ruleset, true);
+            return true;
+        }
+        catch (error) {
+            this.#lastError = error instanceof Error ? error.message : String(error);
+            this.options.onError?.(error);
+            return false;
+        }
+    }
+    #set(ruleset, persist) {
+        this.#ruleset = ruleset;
+        this.#loadedAt = new Date();
+        if (persist)
+            this.#lastError = null;
+        for (const listener of this.#listeners) {
+            try {
+                listener(ruleset);
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (persist && this.options.snapshotPath)
+            void this.#snapshot(ruleset);
+    }
+    async #snapshot(ruleset) {
+        const path = this.options.snapshotPath;
+        try {
+            await mkdir(dirname(path), { recursive: true });
+            // Write-then-rename: a crash mid-write never leaves a truncated snapshot.
+            await writeFile(`${path}.tmp`, JSON.stringify(ruleset));
+            await rename(`${path}.tmp`, path);
+        }
+        catch (error) {
+            this.options.onError?.(error);
+        }
+    }
+    /** Reads `event: ruleset` messages; reconnects with backoff while the source runs. */
+    async #openStream() {
+        let backoff = 1000;
+        while (!this.#stopped) {
+            this.#stream = new AbortController();
+            try {
+                const response = await this.#fetch(`${this.#base}/v1/ruleset/stream`, {
+                    headers: { ...(await this.#headers()), accept: 'text/event-stream' },
+                    signal: this.#stream.signal,
+                });
+                if (response.status === 401)
+                    this.options.token.invalidate?.();
+                if (!response.ok || !response.body)
+                    throw new Error(`stream answered ${response.status}`);
+                this.#streaming = true;
+                backoff = 1000;
+                const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+                let buffer = '';
+                for (;;) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += value;
+                    let boundary = buffer.indexOf('\n\n');
+                    while (boundary !== -1) {
+                        const message = buffer.slice(0, boundary);
+                        buffer = buffer.slice(boundary + 2);
+                        if (/^event: ruleset$/m.test(message))
+                            void this.refresh();
+                        boundary = buffer.indexOf('\n\n');
+                    }
+                }
+            }
+            catch (error) {
+                if (this.#stopped)
+                    break;
+                this.options.onError?.(error);
+            }
+            finally {
+                this.#streaming = false;
+            }
+            if (this.#stopped)
+                break;
+            // The server closes the stream when the token expires; reconnect fetches a fresh one.
+            await new Promise((resolve) => setTimeout(resolve, backoff).unref());
+            backoff = Math.min(backoff * 2, 30_000);
+            void this.refresh();
+        }
+    }
+    status() {
+        return {
+            version: this.#ruleset.version,
+            loadedAt: this.#loadedAt,
+            lastError: this.#lastError,
+            stale: this.#lastError !== null && this.#loadedAt !== null,
+            mode: this.#streaming ? 'stream' : 'poll',
+        };
+    }
+    async stop() {
+        this.#stopped = true;
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#stream?.abort();
+    }
+}
+//# sourceMappingURL=remote_source.js.map

package/dist/src/topology/remote_source.js.map

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

package/dist/src/topology/token.d.ts

@@ -0,0 +1,36 @@
+/** Where a tenant gets the bearer token it presents to the control-plane. */
+export interface TokenSource {
+    get(): Promise<string>;
+    /** Drops a cached token (after a 401), so the next `get` fetches a fresh one. */
+    invalidate?(): void;
+}
+export interface ClientCredentialsOptions {
+    /** OAuth token endpoint (authkit-server: `<issuer>/oauth/token`). */
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    /** Resource the token is for. Default `flags`. */
+    audience?: string;
+    /** Default: read rules, write events and declarations. */
+    scope?: string;
+    /** Refresh this long before expiry (ms). Default 30000. */
+    leewayMs?: number;
+    fetch?: typeof fetch;
+}
+export declare const TENANT_SCOPES: {
+    readonly rulesetRead: 'flags:ruleset:read';
+    readonly eventsWrite: 'flags:events:write';
+    readonly declarationsWrite: 'flags:declarations:write';
+    readonly ofrepEvaluate: 'flags:ofrep:evaluate';
+};
+export declare const tokens: {
+    /** A fixed token (a shared secret). */
+    static(token: string): TokenSource;
+    /**
+     * OAuth 2.0 client credentials (RFC 6749 §4.4) — with authkit-server, register the app as a
+     * confidential client with the `client_credentials` grant. Tokens are cached until shortly before
+     * they expire; concurrent callers share one in-flight request.
+     */
+    clientCredentials(options: ClientCredentialsOptions): TokenSource;
+};
+//# sourceMappingURL=token.d.ts.map

package/dist/src/topology/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/topology/token.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACvB,iFAAiF;IACjF,UAAU,CAAC,IAAI,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,eAAO,MAAM,aAAa;aACxB,WAAW,EAAE,oBAAoB;aACjC,WAAW,EAAE,oBAAoB;aACjC,iBAAiB,EAAE,0BAA0B;aAC7C,aAAa,EAAE,sBAAsB;CAC7B,CAAC;AAEX,eAAO,MAAM,MAAM;IACjB,uCAAuC;IACvC,MAAM,QAAQ,MAAM,GAAG,WAAW;IAIlC;;;;OAIG;IACH,iBAAiB,UAAU,wBAAwB,GAAG,WAAW;CAiDlE,CAAC"}

package/dist/src/topology/token.js

@@ -0,0 +1,68 @@
+export const TENANT_SCOPES = {
+    rulesetRead: 'flags:ruleset:read',
+    eventsWrite: 'flags:events:write',
+    declarationsWrite: 'flags:declarations:write',
+    ofrepEvaluate: 'flags:ofrep:evaluate',
+};
+export const tokens = {
+    /** A fixed token (a shared secret). */
+    static(token) {
+        return { get: async () => token };
+    },
+    /**
+     * OAuth 2.0 client credentials (RFC 6749 §4.4) — with authkit-server, register the app as a
+     * confidential client with the `client_credentials` grant. Tokens are cached until shortly before
+     * they expire; concurrent callers share one in-flight request.
+     */
+    clientCredentials(options) {
+        const fetcher = options.fetch ?? fetch;
+        let cached;
+        let inflight;
+        const leeway = options.leewayMs ?? 30_000;
+        const fetchToken = async () => {
+            const body = new URLSearchParams({
+                grant_type: 'client_credentials',
+                audience: options.audience ?? 'flags',
+                resource: options.audience ?? 'flags',
+                scope: options.scope ??
+                    [
+                        TENANT_SCOPES.rulesetRead,
+                        TENANT_SCOPES.eventsWrite,
+                        TENANT_SCOPES.declarationsWrite,
+                    ].join(' '),
+            });
+            const response = await fetcher(options.tokenUrl, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/x-www-form-urlencoded',
+                    authorization: `Basic ${Buffer.from(`${encodeURIComponent(options.clientId)}:${encodeURIComponent(options.clientSecret)}`).toString('base64')}`,
+                },
+                body,
+            });
+            if (!response.ok)
+                throw new Error(`token endpoint answered ${response.status}: ${await response.text()}`);
+            const json = (await response.json());
+            if (!json.access_token)
+                throw new Error('token endpoint returned no access_token');
+            cached = {
+                token: json.access_token,
+                expiresAt: Date.now() + (json.expires_in ?? 300) * 1000,
+            };
+            return json.access_token;
+        };
+        return {
+            async get() {
+                if (cached && cached.expiresAt - leeway > Date.now())
+                    return cached.token;
+                inflight ??= fetchToken().finally(() => {
+                    inflight = undefined;
+                });
+                return inflight;
+            },
+            invalidate() {
+                cached = undefined;
+            },
+        };
+    },
+};
+//# sourceMappingURL=token.js.map

package/dist/src/topology/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../../src/topology/token.ts"],"names":[],"mappings":"AAqBA,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,WAAW,EAAE,oBAAoB;IACjC,WAAW,EAAE,oBAAoB;IACjC,iBAAiB,EAAE,0BAA0B;IAC7C,aAAa,EAAE,sBAAsB;CAC7B,CAAC;AAEX,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,uCAAuC;IACvC,MAAM,CAAC,KAAa;QAClB,OAAO,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,iBAAiB,CAAC,OAAiC;QACjD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;QACvC,IAAI,MAAwD,CAAC;QAC7D,IAAI,QAAqC,CAAC;QAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC;QAC1C,MAAM,UAAU,GAAG,KAAK,IAAI,EAAE;YAC5B,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC;gBAC/B,UAAU,EAAE,oBAAoB;gBAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO;gBACrC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO;gBACrC,KAAK,EACH,OAAO,CAAC,KAAK;oBACb;wBACE,aAAa,CAAC,WAAW;wBACzB,aAAa,CAAC,WAAW;wBACzB,aAAa,CAAC,iBAAiB;qBAChC,CAAC,IAAI,CAAC,GAAG,CAAC;aACd,CAAC,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE;gBAC/C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,mCAAmC;oBACnD,aAAa,EAAE,SAAS,MAAM,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,kBAAkB,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;iBAChJ;gBACD,IAAI;aACL,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,EAAE;gBACd,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,CAAC,MAAM,KAAK,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1F,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAmD,CAAC;YACvF,IAAI,CAAC,IAAI,CAAC,YAAY;gBAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YACnF,MAAM,GAAG;gBACP,KAAK,EAAE,IAAI,CAAC,YAAY;gBACxB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC,GAAG,IAAI;aACxD,CAAC;YACF,OAAO,IAAI,CAAC,YAAY,CAAC;QAC3B,CAAC,CAAC;QACF,OAAO;YACL,KAAK,CAAC,GAAG;gBACP,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE;oBAAE,OAAO,MAAM,CAAC,KAAK,CAAC;gBAC1E,QAAQ,KAAK,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;oBACrC,QAAQ,GAAG,SAAS,CAAC;gBACvB,CAAC,CAAC,CAAC;gBACH,OAAO,QAAQ,CAAC;YAClB,CAAC;YACD,UAAU;gBACR,MAAM,GAAG,SAAS,CAAC;YACrB,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/src/topology/verify.d.ts

@@ -0,0 +1,88 @@
+import type { Subject } from '../subject.js';
+/**
+ * What a control-plane trusts about a request: derived from the token, never from the body. Same
+ * shape as `@adonis-agora/durable`'s `VerifiedTenant`, so one verifier can serve both.
+ */
+export interface VerifiedTenant {
+    /** The tenant's partition (its app name). */
+    tenant: string;
+    /** Scopes granted (see `TENANT_SCOPES`). */
+    capabilities?: string[] | undefined;
+    /** The environment whose ruleset this tenant reads. Default: the control-plane's. */
+    environment?: string;
+    /** Epoch ms after which streams opened with this token must close. */
+    expiresAt?: number;
+}
+export type TenantVerifier = (input: {
+    token?: string | undefined;
+    tenant?: string | undefined;
+}) => VerifiedTenant | null | Promise<VerifiedTenant | null>;
+export interface SharedSecretTenant {
+    secret: string;
+    environment?: string;
+    /** Default: every tenant scope. */
+    capabilities?: string[];
+}
+export interface AuthkitVerifierOptions {
+    /** The authkit-server issuer (the `iss` claim). */
+    issuer: string;
+    /** Its JWKS URI. Default `<issuer>/.well-known/jwks.json`. */
+    jwksUri?: string;
+    /** Expected `aud`. Default `flags`. */
+    audience?: string | string[];
+    /** Claim holding the partition. Default `client_id`. */
+    partitionClaim?: string;
+    /** Partition → environment, when tenants read different environments. */
+    environments?: Record<string, string>;
+    /** Accept tokens without RFC 9068's `typ: at+jwt`. Default false. */
+    allowAnyTyp?: boolean;
+    /** @internal Also return the verified claims (used by the browser verifier). */
+    claims?: boolean;
+}
+export declare const verifiers: {
+    /**
+     * One secret per tenant, compared in constant time. The request names its partition with the
+     * `x-flags-tenant` header; the secret proves it.
+     */
+    sharedSecret(tenants: Record<string, string | SharedSecretTenant>): TenantVerifier;
+    /**
+     * JWT access tokens issued by authkit-server (`client_credentials`), verified locally against its
+     * JWKS through `@adonis-agora/authkit-client` (optional peer). The partition comes from the
+     * token's `client_id` claim and the capabilities from its `scope`.
+     */
+    authkit(options: AuthkitVerifierOptions): TenantVerifier;
+};
+/** A browser's verified identity: who is evaluating, from a token the browser cannot forge. */
+export interface VerifiedUser {
+    /** Absent for anonymous visitors: they get static values only (no targeting key). */
+    subject?: Subject;
+    /** The environment whose ruleset applies. Default: the control-plane's. */
+    environment?: string;
+    /** The app the browser belongs to (stamped on its events). Default `browser`. */
+    app?: string;
+    /** Epoch ms after which streams opened with this token close. */
+    expiresAt?: number;
+}
+export type UserVerifier = (input: {
+    token?: string | undefined;
+}) => VerifiedUser | null | Promise<VerifiedUser | null>;
+export interface AuthkitUserVerifierOptions {
+    issuer: string;
+    jwksUri?: string;
+    /** Expected `aud` of the user's access token (your API / the flags server). */
+    audience: string | string[];
+    /** Partition → environment, keyed by the token's `client_id` (the app the user signed into). */
+    environments?: Record<string, string>;
+    allowAnyTyp?: boolean;
+}
+export declare const userVerifiers: {
+    /**
+     * An authkit access token held by the client itself — a mobile app or SPA that signs in with
+     * PKCE — verified against the issuer's JWKS. Browsers of an Adonis app with a session use the
+     * app's token endpoint instead (`browser` in `config/flags.ts`). The
+     * subject is the `sub` claim — the same person in every app — and `email`, `roles`/`global_roles`
+     * and the `org_*` claims become trusted targeting attributes.
+     */
+    authkit(options: AuthkitUserVerifierOptions): UserVerifier;
+};
+//# sourceMappingURL=verify.d.ts.map

package/dist/src/topology/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/topology/verify.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACpC,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE;IACnC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,KAAK,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gFAAgF;IAChF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAUD,eAAO,MAAM,SAAS;IACpB;;;OAGG;IACH,YAAY,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAAC,GAAG,cAAc;IAelF;;;;OAIG;IACH,OAAO,UAAU,sBAAsB,GAAG,cAAc;CA4CzD,CAAC;AAEF,+FAA+F;AAC/F,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B,KAAK,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;AAEzD,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,aAAa;IACxB;;;;;;OAMG;IACH,OAAO,UAAU,0BAA0B,GAAG,YAAY;CAwC3D,CAAC"}

package/dist/src/topology/verify.js

@@ -0,0 +1,128 @@
+import { timingSafeEqual } from 'node:crypto';
+import { TENANT_SCOPES } from './token.js';
+const ALL_SCOPES = Object.values(TENANT_SCOPES);
+function sameSecret(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+export const verifiers = {
+    /**
+     * One secret per tenant, compared in constant time. The request names its partition with the
+     * `x-flags-tenant` header; the secret proves it.
+     */
+    sharedSecret(tenants) {
+        return ({ token, tenant }) => {
+            if (!token || !tenant)
+                return null;
+            const entry = tenants[tenant];
+            if (entry === undefined)
+                return null;
+            const config = typeof entry === 'string' ? { secret: entry } : entry;
+            if (!sameSecret(token, config.secret))
+                return null;
+            return {
+                tenant,
+                capabilities: config.capabilities ?? [...ALL_SCOPES],
+                ...(config.environment ? { environment: config.environment } : {}),
+            };
+        };
+    },
+    /**
+     * JWT access tokens issued by authkit-server (`client_credentials`), verified locally against its
+     * JWKS through `@adonis-agora/authkit-client` (optional peer). The partition comes from the
+     * token's `client_id` claim and the capabilities from its `scope`.
+     */
+    authkit(options) {
+        const issuer = options.issuer.replace(/\/$/, '');
+        let verify;
+        return async ({ token }) => {
+            if (!token)
+                return null;
+            if (!verify) {
+                try {
+                    const mod = (await import('@adonis-agora/authkit-client'));
+                    verify = mod.verifyJwtAccessToken;
+                }
+                catch {
+                    throw new Error('@adonis-agora/flags: verifiers.authkit() needs "@adonis-agora/authkit-client". Install it, or use verifiers.sharedSecret().');
+                }
+            }
+            let claims;
+            try {
+                claims = await verify(token, {
+                    issuer: options.issuer,
+                    jwksUri: options.jwksUri ?? `${issuer}/.well-known/jwks.json`,
+                    audience: options.audience ?? 'flags',
+                    ...(options.allowAnyTyp ? { allowAnyTyp: true } : {}),
+                });
+            }
+            catch {
+                return null;
+            }
+            const partition = claims[options.partitionClaim ?? 'client_id'];
+            if (typeof partition !== 'string' || partition.length === 0)
+                return null;
+            const scope = typeof claims.scope === 'string' ? claims.scope.split(/\s+/).filter(Boolean) : [];
+            const environment = options.environments?.[partition];
+            return {
+                tenant: partition,
+                ...(options.claims ? { claims } : {}),
+                capabilities: scope,
+                ...(environment ? { environment } : {}),
+                ...(typeof claims.exp === 'number' ? { expiresAt: claims.exp * 1000 } : {}),
+            };
+        };
+    },
+};
+export const userVerifiers = {
+    /**
+     * An authkit access token held by the client itself — a mobile app or SPA that signs in with
+     * PKCE — verified against the issuer's JWKS. Browsers of an Adonis app with a session use the
+     * app's token endpoint instead (`browser` in `config/flags.ts`). The
+     * subject is the `sub` claim — the same person in every app — and `email`, `roles`/`global_roles`
+     * and the `org_*` claims become trusted targeting attributes.
+     */
+    authkit(options) {
+        const tenant = verifiers.authkit({
+            issuer: options.issuer,
+            audience: options.audience,
+            partitionClaim: 'sub',
+            ...(options.jwksUri ? { jwksUri: options.jwksUri } : {}),
+            ...(options.allowAnyTyp ? { allowAnyTyp: true } : {}),
+            claims: true,
+        });
+        return async ({ token }) => {
+            const verified = (await tenant({ token }));
+            if (!verified?.claims)
+                return null;
+            const claims = verified.claims;
+            const attributes = {};
+            const email = typeof claims.email === 'string' ? claims.email : undefined;
+            if (email) {
+                attributes.email = email;
+                attributes.emailDomain = email.split('@')[1]?.toLowerCase();
+            }
+            const roles = claims.global_roles ?? claims.roles;
+            if (Array.isArray(roles))
+                attributes.globalRoles = roles.map(String);
+            for (const [claim, attribute] of [
+                ['org_id', 'orgId'],
+                ['org_slug', 'orgSlug'],
+                ['org_role', 'orgRole'],
+            ]) {
+                if (typeof claims[claim] === 'string')
+                    attributes[attribute] = claims[claim];
+            }
+            const clientId = typeof claims.client_id === 'string' ? claims.client_id : undefined;
+            const environment = clientId ? options.environments?.[clientId] : undefined;
+            return {
+                subject: { id: verified.tenant, type: 'user', attributes },
+                ...(environment ? { environment } : {}),
+                ...(clientId ? { app: clientId } : {}),
+                ...(verified.expiresAt ? { expiresAt: verified.expiresAt } : {}),
+            };
+        };
+    },
+};
+//# sourceMappingURL=verify.js.map

package/dist/src/topology/verify.js.map

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

package/dist/src/transports/db_transport.d.ts

@@ -0,0 +1,55 @@
+import { type FlagEvent } from '../events/event.js';
+import { type SchemaOptions } from '../schema.js';
+import { type Dialect, type SqlClient, type SqlDatabase } from '../sql.js';
+import type { Delivery, PublishOptions, SinkStatus, Transport } from './transport.js';
+export interface DbTransportOptions extends SchemaOptions {
+    /**
+     * MySQL only. InnoDB hands out auto-increment ids before commit, so a slow transaction can
+     * commit an id lower than one already relayed. The relay only reads events older than this
+     * window (ms) to leave such transactions time to commit. Default 10000. Postgres does not need
+     * it (it orders by transaction id and reads only finished transactions); SQLite has a single
+     * writer.
+     */
+    mysqlSafetyMs?: number;
+    autoCreateSchema?: boolean;
+}
+/**
+ * The event log in your database (`flags_events`), with one cursor per sink in
+ * `flags_sink_cursors`. The only transactional transport: `publish` accepts the caller's Lucid
+ * transaction.
+ *
+ * Leases are `UPDATE … WHERE lease expired` (no transaction held open while a sink sends), and the
+ * cursor only moves while the lease is still ours, so a replica that stalled past its lease cannot
+ * move it back. Delivery is at-least-once; sinks dedupe by event id.
+ *
+ * Gap safety: ids are assigned before commit, so reading strictly by id could skip an event whose
+ * transaction committed late. On Postgres the cursor is `(xid, id)` and the relay reads only rows of
+ * transactions older than the oldest still running (`pg_snapshot_xmin`), which closes the gap
+ * exactly. MySQL uses a time window (`mysqlSafetyMs`); SQLite serializes writers.
+ */
+export declare class DbTransport implements Transport {
+    #private;
+    readonly db: SqlDatabase;
+    private readonly options;
+    readonly name = "db";
+    readonly capabilities: {
+        transactional: boolean;
+        durable: boolean;
+    };
+    readonly dialect: Dialect;
+    constructor(db: SqlDatabase, options?: DbTransportOptions);
+    setup(): Promise<void>;
+    publish(events: FlagEvent[], options?: PublishOptions): Promise<void>;
+    consume(sink: string, options: {
+        batchSize: number;
+        leaseMs: number;
+        owner: string;
+    }): Promise<Delivery | null>;
+    rewind(sink: string): Promise<void>;
+    status(sinks: string[]): Promise<SinkStatus[]>;
+    safePruneId(sinks: string[]): Promise<number>;
+}
+export declare function toEvent(row: Record<string, unknown>): FlagEvent;
+/** Exposed for the db transport's SQL client typing in tests. */
+export type { SqlClient };
+//# sourceMappingURL=db_transport.d.ts.map

package/dist/src/transports/db_transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db_transport.d.ts","sourceRoot":"","sources":["../../../src/transports/db_transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAA4C,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAC5F,OAAO,EACL,KAAK,OAAO,EAMZ,KAAK,SAAS,EACd,KAAK,WAAW,EAEjB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEtF,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAmBD;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,YAAW,SAAS;;IAMzC,QAAQ,CAAC,EAAE,EAAE,WAAW;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,QAAQ,CAAC,IAAI,QAAQ;IACrB,QAAQ,CAAC,YAAY;QAAK,aAAa;QAAQ,OAAO;MAAS;IAC/D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,YACW,EAAE,EAAE,WAAW,EACP,OAAO,GAAE,kBAAuB,EAGlD;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;IAEK,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B9E;IAEK,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAC7D,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAmE1B;IAuCK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxC;IAEK,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CA0BnD;IAEK,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBlD;CACF;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAqB/D;AAED,iEAAiE;AACjE,YAAY,EAAE,SAAS,EAAE,CAAC"}