@authzflow/server 0.0.0-stage → 0.1.0-beta.1

package/dist/change-feed.d.ts

@@ -0,0 +1,67 @@
+import type { CheckResult, CheckResponse } from './index.js';
+export interface StreamPosition {
+    epoch: string;
+    sequence: string;
+    cursor: string;
+}
+export interface ChangeBatch {
+    binding: string;
+    epoch: string;
+    from_sequence: string;
+    through_sequence: string;
+    next_cursor: string;
+    changes: {
+        sequence: string;
+        target: {
+            kind: 'scope' | 'resource';
+            id: string;
+        };
+        action: 'revoke' | 'revalidate' | 'invalidate' | 'purge' | 'grant';
+    }[];
+}
+/** Host serializes checks and all relevant permission mutations in the same barrier.
+ * Append a conservative invalidation durably BEFORE changing the upstream ACL.
+ * Only a successful fresh check can grant access. Unknown/expired cursors reset.
+ */
+export interface ChangeJournal<Target> {
+    barrier<T>(run: () => Promise<T>): Promise<T>;
+    subscribe(binding: string, target: Target): Promise<StreamPosition>;
+    read(binding: string, target: Target, cursor: string, limit: number): Promise<{
+        batch: ChangeBatch;
+        hasMore: boolean;
+    }>;
+}
+export type FeedResult = {
+    status: number;
+    headers: Readonly<{
+        'Cache-Control': 'no-store';
+    }>;
+    body: unknown;
+};
+export interface ChangeFeedOptions<Context, Target> {
+    authenticate(context: Context): Promise<{
+        binding: string;
+    } | null>;
+    check(input: {
+        query: Readonly<Record<string, unknown>>;
+        context: Context;
+        target: Target;
+    }): Promise<CheckResult>;
+    journal: ChangeJournal<Target>;
+}
+export interface ChangeFeed<Context, Target> {
+    snapshot(input: {
+        query: Readonly<Record<string, unknown>>;
+        context: Context;
+        target: Target;
+    }): Promise<FeedResult>;
+    changes(input: {
+        query: Readonly<Record<string, unknown>>;
+        context: Context;
+        target: Target;
+    }): Promise<FeedResult>;
+}
+export type StreamCheck = CheckResponse & {
+    stream: StreamPosition;
+};
+export declare function createChangeFeed<Context, Target>(options: ChangeFeedOptions<Context, Target>): ChangeFeed<Context, Target>;

package/dist/change-feed.js

@@ -0,0 +1,40 @@
+export function createChangeFeed(options) {
+    const headers = Object.freeze({ 'Cache-Control': 'no-store' });
+    const failure = (status, code) => ({ status, headers, body: { error: { code } } });
+    return {
+        async snapshot(input) {
+            try {
+                return await options.journal.barrier(async () => {
+                    const result = await options.check(input);
+                    if (result.status !== 200)
+                        return result;
+                    const stream = await options.journal.subscribe(result.body.binding, input.target);
+                    return { ...result, headers, body: { ...result.body, stream } };
+                });
+            }
+            catch {
+                return failure(503, 'authz_changes_unavailable');
+            }
+        },
+        async changes({ query, context, target }) {
+            const requestId = query.requestId, cursor = query.cursor;
+            if (typeof requestId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(requestId)
+                || typeof cursor !== 'string' || !cursor || cursor.length > 8192
+                || Object.keys(query).length !== 2)
+                return failure(400, 'invalid_authz_changes');
+            try {
+                const identity = await options.authenticate(context);
+                if (!identity)
+                    return failure(401, 'user_session_required');
+                if (typeof identity.binding !== 'string' || !identity.binding || identity.binding.length > 4096)
+                    throw Error();
+                const result = await options.journal.barrier(() => options.journal.read(identity.binding, target, cursor, 100));
+                return { status: 200, headers, body: { schemaVersion: 1, requestId, ...result } };
+            }
+            catch (error) {
+                return error instanceof Error && error.message === 'cursor_reset_required'
+                    ? failure(409, 'reset_required') : failure(503, 'authz_changes_unavailable');
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+export { createChangeFeed, type ChangeFeed, type ChangeFeedOptions, type ChangeJournal, type ChangeBatch, type StreamPosition, type StreamCheck } from './change-feed.js';
+export type ReadPolicy = {
+    mode: 'online_only';
+} | {
+    mode: 'offline_ttl';
+    ttlMinutes: number;
+};
+export type CheckMetadata = {
+    scopeId: string;
+    resourceId: string;
+    contentHash: string;
+};
+export type AuthorizationDecision = {
+    allowed: true;
+    metadata: CheckMetadata;
+} | {
+    allowed: false;
+    reason: 'forbidden' | 'not_found';
+};
+export type CheckResponse = CheckMetadata & {
+    schemaVersion: 1;
+    mode: 'check_only';
+    requestId: string;
+    binding: string;
+    epoch: string;
+    leaseMs: number;
+    readPolicy: {
+        mode: 'online_only' | 'offline_ttl';
+        maxOfflineMs: number;
+    };
+};
+export type CheckError = 'invalid_authz_check' | 'user_session_required' | 'access_required' | 'resource_not_found' | 'authz_check_unavailable';
+export type CheckResult = {
+    status: 200;
+    headers: Readonly<{
+        'Cache-Control': 'no-store';
+    }>;
+    body: CheckResponse;
+} | {
+    status: 400 | 401 | 403 | 404 | 503;
+    headers: Readonly<{
+        'Cache-Control': 'no-store';
+    }>;
+    body: {
+        error: {
+            code: CheckError;
+        };
+    };
+};
+export type ProviderOptions<Context, Principal, Target> = {
+    authenticate(context: Context): Promise<{
+        binding: string;
+        principal: Principal;
+    } | null>;
+    authorize(input: {
+        context: Context;
+        principal: Principal;
+        target: Target;
+    }): Promise<AuthorizationDecision>;
+    readPolicy?: ReadPolicy;
+    leaseMs?: number;
+};
+export type CheckProvider<Context, Target> = {
+    check(input: {
+        query: Readonly<Record<string, unknown>>;
+        context: Context;
+        target: Target;
+    }): Promise<CheckResult>;
+};
+export declare function createCheckProvider<Context, Principal, Target>(options: ProviderOptions<Context, Principal, Target>): CheckProvider<Context, Target>;
+export { createResourceGroupFeed, createResourceGroupCheck, type ResourceGroupJournal, type ResourceGroupTarget, type ResourceGroupPosition, type ResourceGroupFeedOptions } from './resource-group-feed.js';

package/dist/index.js

@@ -0,0 +1,61 @@
+export { createChangeFeed } from './change-feed.js';
+export function createCheckProvider(options) {
+    const policy = options.readPolicy ?? { mode: 'online_only' };
+    const maxOfflineMs = policy.mode === 'offline_ttl' ? policy.ttlMinutes * 60_000 : 0;
+    const leaseMs = options.leaseMs ?? 5000;
+    if (!['online_only', 'offline_ttl'].includes(policy.mode)
+        || (policy.mode === 'offline_ttl' && typeof policy.ttlMinutes !== 'number')
+        || !Number.isSafeInteger(maxOfflineMs) || maxOfflineMs < 0 || maxOfflineMs > 86_400_000
+        || (policy.mode === 'offline_ttl' && maxOfflineMs === 0)
+        || !Number.isSafeInteger(leaseMs) || leaseMs < 1 || leaseMs > 5000
+        || typeof options.authenticate !== 'function' || typeof options.authorize !== 'function') {
+        throw new Error('authz_server_config_invalid');
+    }
+    const readPolicy = Object.freeze({ mode: policy.mode, maxOfflineMs });
+    const headers = Object.freeze({ 'Cache-Control': 'no-store' });
+    const { authenticate, authorize } = options;
+    return {
+        async check({ query, context, target }) {
+            // Copy the nonce before awaiting host I/O; client input never supplies identity or policy.
+            const requestId = query.requestId;
+            if (typeof requestId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(requestId)
+                || Object.keys(query).length !== 1) {
+                return { status: 400, headers, body: { error: { code: 'invalid_authz_check' } } };
+            }
+            try {
+                const identity = await authenticate(context);
+                if (identity === null)
+                    return { status: 401, headers, body: { error: { code: 'user_session_required' } } };
+                if (typeof identity.binding !== 'string' || identity.binding.length === 0 || identity.binding.length > 4096) {
+                    throw new Error('authz_adapter_invalid');
+                }
+                const binding = identity.binding;
+                const decision = await authorize({ context, principal: identity.principal, target });
+                if (decision.allowed === false) {
+                    if (decision.reason === 'forbidden')
+                        return { status: 403, headers, body: { error: { code: 'access_required' } } };
+                    if (decision.reason === 'not_found')
+                        return { status: 404, headers, body: { error: { code: 'resource_not_found' } } };
+                    throw new Error('authz_adapter_invalid');
+                }
+                if (decision.allowed !== true)
+                    throw new Error('authz_adapter_invalid');
+                const { scopeId, resourceId, contentHash } = decision.metadata;
+                if (typeof scopeId !== 'string' || scopeId.length === 0 || scopeId.length > 4096
+                    || typeof resourceId !== 'string' || resourceId.length === 0 || resourceId.length > 4096
+                    || typeof contentHash !== 'string' || !/^[a-f0-9]{64}$/.test(contentHash)) {
+                    throw new Error('authz_adapter_invalid');
+                }
+                return { status: 200, headers, body: {
+                        schemaVersion: 1, mode: 'check_only', requestId, binding,
+                        epoch: globalThis.crypto.randomUUID(), scopeId, resourceId, contentHash, leaseMs, readPolicy,
+                    } };
+            }
+            catch {
+                // Host exceptions can contain credentials, SQL or private URLs. Never return or log them.
+                return { status: 503, headers, body: { error: { code: 'authz_check_unavailable' } } };
+            }
+        },
+    };
+}
+export { createResourceGroupFeed, createResourceGroupCheck } from './resource-group-feed.js';

package/dist/resource-group-feed.d.ts

@@ -0,0 +1,75 @@
+export interface ResourceGroupTarget {
+    resourceGroupId: string;
+}
+export interface ResourceGroupPosition {
+    epoch: string;
+    sequence: string;
+    cursor: string;
+}
+export interface ResourceGroupJournal<Target extends ResourceGroupTarget> {
+    barrier<T>(work: () => Promise<T>): Promise<T>;
+    /** Authoritative entitlement, including a bounded former-subscriber revocation path. */
+    subscribe(binding: string, target: Target): Promise<ResourceGroupPosition>;
+    read(binding: string, target: Target, cursor: string, limit: number): Promise<{
+        batch: {
+            binding: string;
+            resourceGroupId: string;
+            epoch: string;
+            fromSequence: string;
+            throughSequence: string;
+            nextCursor: string;
+            changes: {
+                sequence: string;
+                action: 'revoke' | 'revalidate';
+            }[];
+        };
+        hasMore: boolean;
+    }>;
+}
+type FeedResult = {
+    status: number;
+    headers: Readonly<{
+        'Cache-Control': 'no-store';
+    }>;
+    body: unknown;
+};
+export interface ResourceGroupFeedOptions<Context, Target extends ResourceGroupTarget> {
+    authenticate(context: Context): Promise<{
+        binding: string;
+    } | null>;
+    journal: ResourceGroupJournal<Target>;
+}
+/** Metadata-only Group feed. Product journal must enforce cursor and subscriber binding. */
+export declare function createResourceGroupFeed<Context, Target extends ResourceGroupTarget>(options: ResourceGroupFeedOptions<Context, Target>): {
+    subscribe({ query: q, context, target }: {
+        query: Readonly<Record<string, unknown>>;
+        context: Context;
+        target: Target;
+    }): Promise<FeedResult>;
+    changes({ query: q, context, target }: {
+        query: Readonly<Record<string, unknown>>;
+        context: Context;
+        target: Target;
+    }): Promise<FeedResult>;
+};
+/** Attach a trusted Group watermark inside the SAME ACL/journal barrier. No group-wide allow. */
+export declare function createResourceGroupCheck<Context, Target>(options: {
+    check(input: {
+        query: Readonly<Record<string, unknown>>;
+        context: Context;
+        target: Target;
+    }): Promise<{
+        status: number;
+        headers: Readonly<{
+            'Cache-Control': 'no-store';
+        }>;
+        body: unknown;
+    }>;
+    resolveGroup(target: Target): Promise<ResourceGroupTarget>;
+    journal: ResourceGroupJournal<ResourceGroupTarget>;
+}): (input: {
+    query: Readonly<Record<string, unknown>>;
+    context: Context;
+    target: Target;
+}) => Promise<FeedResult>;
+export {};

package/dist/resource-group-feed.js

@@ -0,0 +1,78 @@
+/** Metadata-only Group feed. Product journal must enforce cursor and subscriber binding. */
+export function createResourceGroupFeed(options) {
+    const headers = Object.freeze({ 'Cache-Control': 'no-store' });
+    const error = (status, code) => ({ status, headers, body: { error: { code } } });
+    const identity = async (context) => {
+        const actor = await options.authenticate(context);
+        if (actor && (typeof actor.binding !== 'string' || !actor.binding || actor.binding.length > 4096))
+            throw Error('group_identity_invalid');
+        return actor;
+    };
+    const query = (value, cursor) => value && !Array.isArray(value) && typeof value.requestId === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value.requestId) && Object.keys(value).length === (cursor ? 2 : 1) && (!cursor || typeof value.cursor === 'string' && value.cursor.length > 0 && value.cursor.length <= 8192);
+    return {
+        async subscribe({ query: q, context, target }) {
+            if (!query(q, false) || typeof target?.resourceGroupId !== 'string' || !target.resourceGroupId || target.resourceGroupId.length > 4096)
+                return error(400, 'invalid_group_request');
+            try {
+                const actor = await identity(context);
+                if (!actor)
+                    return error(401, 'user_session_required');
+                const position = await options.journal.barrier(() => options.journal.subscribe(actor.binding, target));
+                if (!position || Object.keys(position).sort().join(',') !== 'cursor,epoch,sequence' || typeof position.epoch !== 'string' || !position.epoch || position.epoch.length > 128 || typeof position.cursor !== 'string' || !position.cursor || position.cursor.length > 8192 || typeof position.sequence !== 'string' || !/^(0|[1-9][0-9]*)$/.test(position.sequence) || position.sequence.length > 20 || BigInt(position.sequence) > 18446744073709551615n)
+                    throw Error('group_position_invalid');
+                return { status: 200, headers, body: { schemaVersion: 2, kind: 'resource_group', requestId: q.requestId, binding: actor.binding, resourceGroupId: target.resourceGroupId, position } };
+            }
+            catch (failure) {
+                return failure instanceof Error && failure.message === 'access_required' ? error(403, 'access_required') : error(503, 'group_unavailable');
+            }
+        },
+        async changes({ query: q, context, target }) {
+            if (!query(q, true) || typeof target?.resourceGroupId !== 'string' || !target.resourceGroupId || target.resourceGroupId.length > 4096)
+                return error(400, 'invalid_group_request');
+            try {
+                const actor = await identity(context);
+                if (!actor)
+                    return error(401, 'user_session_required');
+                const result = await options.journal.barrier(() => options.journal.read(actor.binding, target, q.cursor, 100));
+                // The producer also rejects Resource IDs/unknown event fields, not just the consumer.
+                const b = result.batch;
+                if (!b || Object.keys(b).sort().join(',') !== 'binding,changes,epoch,fromSequence,nextCursor,resourceGroupId,throughSequence' || typeof result.hasMore !== 'boolean' || b.binding !== actor.binding || b.resourceGroupId !== target.resourceGroupId || typeof b.epoch !== 'string' || !b.epoch || b.epoch.length > 128 || typeof b.nextCursor !== 'string' || !b.nextCursor || b.nextCursor.length > 8192 || !Array.isArray(b.changes) || b.changes.length > 100 || b.changes.some(e => Object.keys(e).sort().join(',') !== 'action,sequence' || !['revoke', 'revalidate'].includes(e.action)))
+                    throw Error('group_batch_invalid');
+                let previous = BigInt(b.fromSequence);
+                if (!/^(0|[1-9][0-9]*)$/.test(b.fromSequence) || !/^(0|[1-9][0-9]*)$/.test(b.throughSequence))
+                    throw Error('group_batch_invalid');
+                for (const e of b.changes) {
+                    previous++;
+                    if (String(previous) !== e.sequence)
+                        throw Error('group_batch_invalid');
+                }
+                if (String(previous) !== b.throughSequence || previous > 18446744073709551615n)
+                    throw Error('group_batch_invalid');
+                return { status: 200, headers, body: { schemaVersion: 2, kind: 'resource_group', requestId: q.requestId, batch: b, hasMore: result.hasMore } };
+            }
+            catch (failure) {
+                return failure instanceof Error && failure.message === 'cursor_reset_required' ? error(409, 'reset_required') : error(503, 'group_unavailable');
+            }
+        },
+    };
+}
+/** Attach a trusted Group watermark inside the SAME ACL/journal barrier. No group-wide allow. */
+export function createResourceGroupCheck(options) {
+    return async (input) => {
+        try {
+            return await options.journal.barrier(async () => {
+                const result = await options.check(input);
+                if (result.status !== 200)
+                    return result;
+                const body = result.body;
+                if (typeof body?.binding !== 'string')
+                    throw Error('group_identity_invalid');
+                const target = await options.resolveGroup(input.target), position = await options.journal.subscribe(body.binding, target);
+                return { ...result, headers: { 'Cache-Control': 'no-store' }, body: { ...body, resourceGroup: { resourceGroupId: target.resourceGroupId, epoch: position.epoch, sequence: position.sequence } } };
+            });
+        }
+        catch {
+            return { status: 503, headers: { 'Cache-Control': 'no-store' }, body: { error: { code: 'group_check_unavailable' } } };
+        }
+    };
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@authzflow/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "private": false,
+  "type": "module",
+  "author": "Accelflow Inc.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Accelflow/AuthzFlow.git"
+  },
+  "license": "MIT",
+  "description": "Framework-neutral authorization complete-check provider",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  }
+}