@btst/stack 3.0.0-rc.2 → 3.0.0-rc.3

package/dist/authorization/index.d.cts

@@ -0,0 +1,201 @@
+import { z } from 'zod';
+
+declare const permissionSeedMarker: "__btst.authorization.permission-seed.v1";
+declare const permissionDescriptorMarker: "__btst.authorization.permission-descriptor.v1";
+declare const permissionCatalogMarker: "__btst.authorization.permission-catalog.v1";
+declare const authorizationContractTypes: "__btst.authorization.contract-types.v1";
+type AnySchema = z.ZodType<any, any>;
+/** A permission declaration before its stable catalog id has been assigned. */
+interface PermissionSeed<TSchema extends AnySchema | undefined> {
+    readonly [permissionSeedMarker]: true;
+    readonly schema: TSchema;
+}
+type PermissionFacts<TSchema extends AnySchema | undefined> = TSchema extends AnySchema ? z.output<TSchema> : undefined;
+type PermissionInput<TSchema extends AnySchema | undefined> = TSchema extends AnySchema ? [facts: z.input<TSchema>] : [];
+/** A validated permission request passed to client and server evaluators. */
+interface PermissionRequest<TId extends string = string, TSchema extends AnySchema | undefined = AnySchema | undefined> {
+    readonly id: TId;
+    readonly permission: PermissionDescriptor<TId, TSchema>;
+    readonly facts: PermissionFacts<TSchema>;
+}
+/** A stable, callable permission descriptor produced by `definePermissions`. */
+interface PermissionDescriptor<TId extends string = string, TSchema extends AnySchema | undefined = AnySchema | undefined> {
+    (...args: PermissionInput<TSchema>): PermissionRequest<TId, TSchema>;
+    readonly id: TId;
+    readonly schema: TSchema;
+    readonly [permissionDescriptorMarker]: true;
+}
+type PermissionTree = {
+    readonly [key: string]: PermissionTree | PermissionSeed<AnySchema | undefined>;
+};
+type AppendPath<TPath extends string, TKey extends string> = TPath extends "" ? TKey : `${TPath}.${TKey}`;
+type BoundPermissionTree<TTree, TNamespace extends string, TPath extends string = ""> = TTree extends PermissionSeed<infer TSchema> ? PermissionDescriptor<`${TNamespace}:${TPath}`, TSchema> : {
+    readonly [TKey in keyof TTree]: TKey extends string ? BoundPermissionTree<TTree[TKey], TNamespace, AppendPath<TPath, TKey>> : never;
+};
+/** A named catalog of permission descriptors. */
+type PermissionCatalog<TName extends string = string, TTree extends PermissionTree = {}> = BoundPermissionTree<TTree, TName> & {
+    readonly [permissionCatalogMarker]: {
+        readonly name: TName;
+    };
+};
+type AnyPermissionCatalog = PermissionCatalog<string>;
+/** Any schema-backed permission descriptor, for generic plugin APIs. */
+type AnyPermissionDescriptor = PermissionDescriptor<string, AnySchema | undefined>;
+type AnyPermissionRequest = PermissionRequest<string, AnySchema | undefined>;
+/** Declare a permission whose checks do not need record facts. */
+declare function permission(): PermissionSeed<undefined>;
+/** Declare a permission whose fact type is inferred from its runtime schema. */
+declare function permission<TSchema extends AnySchema>(schema: TSchema): PermissionSeed<TSchema>;
+/**
+ * Assign stable ids to a plugin's schema-backed permission declarations.
+ * The returned tree is safe to import from both browser and server modules.
+ */
+declare function definePermissions<const TName extends string, const TTree extends PermissionTree>(name: TName, tree: TTree): PermissionCatalog<TName, TTree>;
+type DescriptorsIn<T> = T extends AnyPermissionDescriptor ? T : T extends object ? {
+    [TKey in keyof T]: TKey extends typeof permissionCatalogMarker ? never : DescriptorsIn<T[TKey]>;
+}[keyof T] : never;
+type RegisteredDescriptor<TCatalogs extends readonly AnyPermissionCatalog[]> = DescriptorsIn<TCatalogs[number]>;
+type RequestFor<TDescriptor> = TDescriptor extends PermissionDescriptor<infer TId, infer TSchema> ? PermissionRequest<TId, TSchema> : never;
+/** Infer validated fact output for a permission descriptor. */
+type PermissionFactsFor<TPermission> = TPermission extends PermissionDescriptor<infer _TId, infer TSchema> ? PermissionFacts<TSchema> : never;
+/** Infer accepted fact input for a permission descriptor. */
+type PermissionInputFor<TPermission> = TPermission extends PermissionDescriptor<infer _TId, infer TSchema> ? TSchema extends AnySchema ? z.input<TSchema> : undefined : never;
+/** Infer the validated request created by a permission descriptor. */
+type PermissionRequestFor<TPermission> = RequestFor<TPermission>;
+interface AuthorizationRuleDefinition {
+    readonly permission: AnyPermissionDescriptor;
+    readonly evaluate: (input: {
+        identity: unknown;
+        facts: unknown;
+    }) => boolean;
+}
+type RulePermission<TPermission, TIdentity> = TPermission extends PermissionDescriptor<infer _TId, infer TSchema> ? {
+    allow: () => AuthorizationRuleDefinition;
+    when: (rule: (input: {
+        identity: TIdentity | null;
+        facts: PermissionFacts<TSchema>;
+    }) => boolean) => AuthorizationRuleDefinition;
+} : never;
+type RuleTree<TTree, TIdentity> = TTree extends AnyPermissionDescriptor ? RulePermission<TTree, TIdentity> : TTree extends object ? {
+    [TKey in keyof TTree as TKey extends typeof permissionCatalogMarker ? never : TKey]: RuleTree<TTree[TKey], TIdentity>;
+} : never;
+type CatalogRuleEntry<TCatalog, TIdentity> = TCatalog extends PermissionCatalog<infer TName, infer _TTree> ? {
+    [TKey in TName]: RuleTree<TCatalog, TIdentity>;
+} : never;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+type RuleCatalogs<TCatalogs extends readonly AnyPermissionCatalog[], TIdentity> = UnionToIntersection<CatalogRuleEntry<TCatalogs[number], TIdentity>>;
+/**
+ * A rule-free authorization vocabulary that can be published independently of
+ * an application's backend implementation.
+ */
+interface AuthorizationContract<TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, TCatalogs extends readonly AnyPermissionCatalog[]> {
+    readonly [authorizationContractTypes]?: {
+        readonly identity: z.output<TIdentitySchema>;
+        readonly identityInput: z.input<TIdentitySchema>;
+        readonly permission: RequestFor<RegisteredDescriptor<TCatalogs>>;
+    };
+    readonly identitySchema: TIdentitySchema;
+    readonly permissions: TCatalogs;
+    readonly permissionIds: readonly string[];
+    readonly version: string;
+    parseIdentity(identity: unknown): z.output<TIdentitySchema> | null;
+    parsePermission(permission: unknown): RequestFor<RegisteredDescriptor<TCatalogs>>;
+}
+/** Any portable authorization contract, for generic adapter APIs. */
+interface AnyAuthorizationContract {
+    readonly [authorizationContractTypes]?: {
+        readonly identity: {
+            id: string;
+        };
+        readonly identityInput: unknown;
+        readonly permission: any;
+    };
+    readonly identitySchema: z.ZodType<{
+        id: string;
+    }, any>;
+    readonly permissions: readonly AnyPermissionCatalog[];
+    readonly permissionIds: readonly string[];
+    readonly version: string;
+    parseIdentity(identity: unknown): {
+        id: string;
+    } | null;
+    parsePermission(permission: unknown): any;
+}
+type ContractIdentitySchema<TContract extends AnyAuthorizationContract> = TContract extends AuthorizationContract<infer TSchema, any> ? TSchema : never;
+type ContractCatalogs<TContract extends AnyAuthorizationContract> = TContract extends AuthorizationContract<any, infer TCatalogs> ? TCatalogs : never;
+/** Infer validated identity output from a portable contract. */
+type AuthorizationContractIdentity<TContract> = TContract extends AnyAuthorizationContract ? NonNullable<TContract[typeof authorizationContractTypes]>["identity"] : never;
+/** Infer accepted identity input from a portable contract. */
+type AuthorizationContractIdentityInput<TContract> = TContract extends AnyAuthorizationContract ? NonNullable<TContract[typeof authorizationContractTypes]>["identityInput"] : never;
+/** Infer registered permission requests from a portable contract. */
+type AuthorizationContractPermissionRequest<TContract> = TContract extends AnyAuthorizationContract ? NonNullable<TContract[typeof authorizationContractTypes]>["permission"] : never;
+/** Define a versioned identity and permission vocabulary without any rules. */
+declare function defineAuthorizationContract<const TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, const TCatalogs extends readonly AnyPermissionCatalog[]>(config: {
+    identity: TIdentitySchema;
+    permissions: TCatalogs;
+}): AuthorizationContract<TIdentitySchema, TCatalogs>;
+/** The shared, synchronous authorization contract used by client and server. */
+interface Authorization<TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, TCatalogs extends readonly AnyPermissionCatalog[]> {
+    readonly contract: AuthorizationContract<TIdentitySchema, TCatalogs>;
+    readonly identitySchema: TIdentitySchema;
+    readonly permissions: TCatalogs;
+    parseIdentity(identity: unknown): z.output<TIdentitySchema> | null;
+    can(request: RequestFor<RegisteredDescriptor<TCatalogs>>, identity: z.input<TIdentitySchema> | null): boolean;
+}
+/** Any one-rule authorization contract, for generic adapter APIs. */
+interface AnyAuthorization {
+    readonly contract: AnyAuthorizationContract;
+    readonly identitySchema: z.ZodType<{
+        id: string;
+    }, any>;
+    readonly permissions: readonly AnyPermissionCatalog[];
+    parseIdentity(identity: unknown): {
+        id: string;
+    } | null;
+    can(request: any, identity: any): boolean;
+}
+/** Infer validated identity output from an authorization contract. */
+type AuthorizationIdentity<TAuthorization> = TAuthorization extends {
+    readonly identitySchema: infer TSchema extends z.ZodType<{
+        id: string;
+    }, any>;
+} ? z.output<TSchema> : never;
+/** Infer accepted identity input from an authorization contract. */
+type AuthorizationIdentityInput<TAuthorization> = TAuthorization extends {
+    readonly identitySchema: infer TSchema extends z.ZodType<{
+        id: string;
+    }, any>;
+} ? z.input<TSchema> : never;
+/** Infer registered permission requests from an authorization contract. */
+type AuthorizationPermissionRequest<TAuthorization> = TAuthorization extends {
+    readonly permissions: infer TCatalogs extends readonly AnyPermissionCatalog[];
+} ? RequestFor<RegisteredDescriptor<TCatalogs>> : never;
+/** Infer stable permission ids registered by an authorization contract. */
+type AuthorizationPermissionId<TAuthorization> = TAuthorization extends Authorization<any, infer TCatalogs> ? RegisteredDescriptor<TCatalogs> extends PermissionDescriptor<infer TId, any> ? TId : never : never;
+/**
+ * Define one browser-safe rule set over a validated identity and registered
+ * permission catalogs. Missing rules deny; rule failures are allowed to
+ * propagate so outages never masquerade as ordinary denials.
+ */
+declare function defineAuthorization<const TContract extends AnyAuthorizationContract>(config: {
+    contract: TContract;
+    rules: (permissions: RuleCatalogs<ContractCatalogs<TContract>, z.output<ContractIdentitySchema<TContract>>>) => readonly AuthorizationRuleDefinition[];
+}): Authorization<ContractIdentitySchema<TContract>, ContractCatalogs<TContract>>;
+declare function defineAuthorization<const TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, const TCatalogs extends readonly AnyPermissionCatalog[]>(config: {
+    identity: TIdentitySchema;
+    permissions: TCatalogs;
+    rules: (permissions: RuleCatalogs<TCatalogs, z.output<TIdentitySchema>>) => readonly AuthorizationRuleDefinition[];
+}): Authorization<TIdentitySchema, TCatalogs>;
+/** Check whether a runtime value has the shape of a permission request. */
+declare function isPermissionRequest(value: unknown): value is AnyPermissionRequest;
+
+export { defineAuthorization, defineAuthorizationContract, definePermissions, isPermissionRequest, permission };
+export type { AnyAuthorization, AnyAuthorizationContract, AnyPermissionDescriptor, Authorization, AuthorizationContract, AuthorizationContractIdentity, AuthorizationContractIdentityInput, AuthorizationContractPermissionRequest, AuthorizationIdentity, AuthorizationIdentityInput, AuthorizationPermissionId, AuthorizationPermissionRequest, PermissionCatalog, PermissionDescriptor, PermissionFactsFor, PermissionInputFor, PermissionRequest, PermissionRequestFor, PermissionSeed };

package/dist/authorization/index.d.mts

@@ -0,0 +1,201 @@
+import { z } from 'zod';
+
+declare const permissionSeedMarker: "__btst.authorization.permission-seed.v1";
+declare const permissionDescriptorMarker: "__btst.authorization.permission-descriptor.v1";
+declare const permissionCatalogMarker: "__btst.authorization.permission-catalog.v1";
+declare const authorizationContractTypes: "__btst.authorization.contract-types.v1";
+type AnySchema = z.ZodType<any, any>;
+/** A permission declaration before its stable catalog id has been assigned. */
+interface PermissionSeed<TSchema extends AnySchema | undefined> {
+    readonly [permissionSeedMarker]: true;
+    readonly schema: TSchema;
+}
+type PermissionFacts<TSchema extends AnySchema | undefined> = TSchema extends AnySchema ? z.output<TSchema> : undefined;
+type PermissionInput<TSchema extends AnySchema | undefined> = TSchema extends AnySchema ? [facts: z.input<TSchema>] : [];
+/** A validated permission request passed to client and server evaluators. */
+interface PermissionRequest<TId extends string = string, TSchema extends AnySchema | undefined = AnySchema | undefined> {
+    readonly id: TId;
+    readonly permission: PermissionDescriptor<TId, TSchema>;
+    readonly facts: PermissionFacts<TSchema>;
+}
+/** A stable, callable permission descriptor produced by `definePermissions`. */
+interface PermissionDescriptor<TId extends string = string, TSchema extends AnySchema | undefined = AnySchema | undefined> {
+    (...args: PermissionInput<TSchema>): PermissionRequest<TId, TSchema>;
+    readonly id: TId;
+    readonly schema: TSchema;
+    readonly [permissionDescriptorMarker]: true;
+}
+type PermissionTree = {
+    readonly [key: string]: PermissionTree | PermissionSeed<AnySchema | undefined>;
+};
+type AppendPath<TPath extends string, TKey extends string> = TPath extends "" ? TKey : `${TPath}.${TKey}`;
+type BoundPermissionTree<TTree, TNamespace extends string, TPath extends string = ""> = TTree extends PermissionSeed<infer TSchema> ? PermissionDescriptor<`${TNamespace}:${TPath}`, TSchema> : {
+    readonly [TKey in keyof TTree]: TKey extends string ? BoundPermissionTree<TTree[TKey], TNamespace, AppendPath<TPath, TKey>> : never;
+};
+/** A named catalog of permission descriptors. */
+type PermissionCatalog<TName extends string = string, TTree extends PermissionTree = {}> = BoundPermissionTree<TTree, TName> & {
+    readonly [permissionCatalogMarker]: {
+        readonly name: TName;
+    };
+};
+type AnyPermissionCatalog = PermissionCatalog<string>;
+/** Any schema-backed permission descriptor, for generic plugin APIs. */
+type AnyPermissionDescriptor = PermissionDescriptor<string, AnySchema | undefined>;
+type AnyPermissionRequest = PermissionRequest<string, AnySchema | undefined>;
+/** Declare a permission whose checks do not need record facts. */
+declare function permission(): PermissionSeed<undefined>;
+/** Declare a permission whose fact type is inferred from its runtime schema. */
+declare function permission<TSchema extends AnySchema>(schema: TSchema): PermissionSeed<TSchema>;
+/**
+ * Assign stable ids to a plugin's schema-backed permission declarations.
+ * The returned tree is safe to import from both browser and server modules.
+ */
+declare function definePermissions<const TName extends string, const TTree extends PermissionTree>(name: TName, tree: TTree): PermissionCatalog<TName, TTree>;
+type DescriptorsIn<T> = T extends AnyPermissionDescriptor ? T : T extends object ? {
+    [TKey in keyof T]: TKey extends typeof permissionCatalogMarker ? never : DescriptorsIn<T[TKey]>;
+}[keyof T] : never;
+type RegisteredDescriptor<TCatalogs extends readonly AnyPermissionCatalog[]> = DescriptorsIn<TCatalogs[number]>;
+type RequestFor<TDescriptor> = TDescriptor extends PermissionDescriptor<infer TId, infer TSchema> ? PermissionRequest<TId, TSchema> : never;
+/** Infer validated fact output for a permission descriptor. */
+type PermissionFactsFor<TPermission> = TPermission extends PermissionDescriptor<infer _TId, infer TSchema> ? PermissionFacts<TSchema> : never;
+/** Infer accepted fact input for a permission descriptor. */
+type PermissionInputFor<TPermission> = TPermission extends PermissionDescriptor<infer _TId, infer TSchema> ? TSchema extends AnySchema ? z.input<TSchema> : undefined : never;
+/** Infer the validated request created by a permission descriptor. */
+type PermissionRequestFor<TPermission> = RequestFor<TPermission>;
+interface AuthorizationRuleDefinition {
+    readonly permission: AnyPermissionDescriptor;
+    readonly evaluate: (input: {
+        identity: unknown;
+        facts: unknown;
+    }) => boolean;
+}
+type RulePermission<TPermission, TIdentity> = TPermission extends PermissionDescriptor<infer _TId, infer TSchema> ? {
+    allow: () => AuthorizationRuleDefinition;
+    when: (rule: (input: {
+        identity: TIdentity | null;
+        facts: PermissionFacts<TSchema>;
+    }) => boolean) => AuthorizationRuleDefinition;
+} : never;
+type RuleTree<TTree, TIdentity> = TTree extends AnyPermissionDescriptor ? RulePermission<TTree, TIdentity> : TTree extends object ? {
+    [TKey in keyof TTree as TKey extends typeof permissionCatalogMarker ? never : TKey]: RuleTree<TTree[TKey], TIdentity>;
+} : never;
+type CatalogRuleEntry<TCatalog, TIdentity> = TCatalog extends PermissionCatalog<infer TName, infer _TTree> ? {
+    [TKey in TName]: RuleTree<TCatalog, TIdentity>;
+} : never;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+type RuleCatalogs<TCatalogs extends readonly AnyPermissionCatalog[], TIdentity> = UnionToIntersection<CatalogRuleEntry<TCatalogs[number], TIdentity>>;
+/**
+ * A rule-free authorization vocabulary that can be published independently of
+ * an application's backend implementation.
+ */
+interface AuthorizationContract<TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, TCatalogs extends readonly AnyPermissionCatalog[]> {
+    readonly [authorizationContractTypes]?: {
+        readonly identity: z.output<TIdentitySchema>;
+        readonly identityInput: z.input<TIdentitySchema>;
+        readonly permission: RequestFor<RegisteredDescriptor<TCatalogs>>;
+    };
+    readonly identitySchema: TIdentitySchema;
+    readonly permissions: TCatalogs;
+    readonly permissionIds: readonly string[];
+    readonly version: string;
+    parseIdentity(identity: unknown): z.output<TIdentitySchema> | null;
+    parsePermission(permission: unknown): RequestFor<RegisteredDescriptor<TCatalogs>>;
+}
+/** Any portable authorization contract, for generic adapter APIs. */
+interface AnyAuthorizationContract {
+    readonly [authorizationContractTypes]?: {
+        readonly identity: {
+            id: string;
+        };
+        readonly identityInput: unknown;
+        readonly permission: any;
+    };
+    readonly identitySchema: z.ZodType<{
+        id: string;
+    }, any>;
+    readonly permissions: readonly AnyPermissionCatalog[];
+    readonly permissionIds: readonly string[];
+    readonly version: string;
+    parseIdentity(identity: unknown): {
+        id: string;
+    } | null;
+    parsePermission(permission: unknown): any;
+}
+type ContractIdentitySchema<TContract extends AnyAuthorizationContract> = TContract extends AuthorizationContract<infer TSchema, any> ? TSchema : never;
+type ContractCatalogs<TContract extends AnyAuthorizationContract> = TContract extends AuthorizationContract<any, infer TCatalogs> ? TCatalogs : never;
+/** Infer validated identity output from a portable contract. */
+type AuthorizationContractIdentity<TContract> = TContract extends AnyAuthorizationContract ? NonNullable<TContract[typeof authorizationContractTypes]>["identity"] : never;
+/** Infer accepted identity input from a portable contract. */
+type AuthorizationContractIdentityInput<TContract> = TContract extends AnyAuthorizationContract ? NonNullable<TContract[typeof authorizationContractTypes]>["identityInput"] : never;
+/** Infer registered permission requests from a portable contract. */
+type AuthorizationContractPermissionRequest<TContract> = TContract extends AnyAuthorizationContract ? NonNullable<TContract[typeof authorizationContractTypes]>["permission"] : never;
+/** Define a versioned identity and permission vocabulary without any rules. */
+declare function defineAuthorizationContract<const TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, const TCatalogs extends readonly AnyPermissionCatalog[]>(config: {
+    identity: TIdentitySchema;
+    permissions: TCatalogs;
+}): AuthorizationContract<TIdentitySchema, TCatalogs>;
+/** The shared, synchronous authorization contract used by client and server. */
+interface Authorization<TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, TCatalogs extends readonly AnyPermissionCatalog[]> {
+    readonly contract: AuthorizationContract<TIdentitySchema, TCatalogs>;
+    readonly identitySchema: TIdentitySchema;
+    readonly permissions: TCatalogs;
+    parseIdentity(identity: unknown): z.output<TIdentitySchema> | null;
+    can(request: RequestFor<RegisteredDescriptor<TCatalogs>>, identity: z.input<TIdentitySchema> | null): boolean;
+}
+/** Any one-rule authorization contract, for generic adapter APIs. */
+interface AnyAuthorization {
+    readonly contract: AnyAuthorizationContract;
+    readonly identitySchema: z.ZodType<{
+        id: string;
+    }, any>;
+    readonly permissions: readonly AnyPermissionCatalog[];
+    parseIdentity(identity: unknown): {
+        id: string;
+    } | null;
+    can(request: any, identity: any): boolean;
+}
+/** Infer validated identity output from an authorization contract. */
+type AuthorizationIdentity<TAuthorization> = TAuthorization extends {
+    readonly identitySchema: infer TSchema extends z.ZodType<{
+        id: string;
+    }, any>;
+} ? z.output<TSchema> : never;
+/** Infer accepted identity input from an authorization contract. */
+type AuthorizationIdentityInput<TAuthorization> = TAuthorization extends {
+    readonly identitySchema: infer TSchema extends z.ZodType<{
+        id: string;
+    }, any>;
+} ? z.input<TSchema> : never;
+/** Infer registered permission requests from an authorization contract. */
+type AuthorizationPermissionRequest<TAuthorization> = TAuthorization extends {
+    readonly permissions: infer TCatalogs extends readonly AnyPermissionCatalog[];
+} ? RequestFor<RegisteredDescriptor<TCatalogs>> : never;
+/** Infer stable permission ids registered by an authorization contract. */
+type AuthorizationPermissionId<TAuthorization> = TAuthorization extends Authorization<any, infer TCatalogs> ? RegisteredDescriptor<TCatalogs> extends PermissionDescriptor<infer TId, any> ? TId : never : never;
+/**
+ * Define one browser-safe rule set over a validated identity and registered
+ * permission catalogs. Missing rules deny; rule failures are allowed to
+ * propagate so outages never masquerade as ordinary denials.
+ */
+declare function defineAuthorization<const TContract extends AnyAuthorizationContract>(config: {
+    contract: TContract;
+    rules: (permissions: RuleCatalogs<ContractCatalogs<TContract>, z.output<ContractIdentitySchema<TContract>>>) => readonly AuthorizationRuleDefinition[];
+}): Authorization<ContractIdentitySchema<TContract>, ContractCatalogs<TContract>>;
+declare function defineAuthorization<const TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, const TCatalogs extends readonly AnyPermissionCatalog[]>(config: {
+    identity: TIdentitySchema;
+    permissions: TCatalogs;
+    rules: (permissions: RuleCatalogs<TCatalogs, z.output<TIdentitySchema>>) => readonly AuthorizationRuleDefinition[];
+}): Authorization<TIdentitySchema, TCatalogs>;
+/** Check whether a runtime value has the shape of a permission request. */
+declare function isPermissionRequest(value: unknown): value is AnyPermissionRequest;
+
+export { defineAuthorization, defineAuthorizationContract, definePermissions, isPermissionRequest, permission };
+export type { AnyAuthorization, AnyAuthorizationContract, AnyPermissionDescriptor, Authorization, AuthorizationContract, AuthorizationContractIdentity, AuthorizationContractIdentityInput, AuthorizationContractPermissionRequest, AuthorizationIdentity, AuthorizationIdentityInput, AuthorizationPermissionId, AuthorizationPermissionRequest, PermissionCatalog, PermissionDescriptor, PermissionFactsFor, PermissionInputFor, PermissionRequest, PermissionRequestFor, PermissionSeed };

package/dist/authorization/index.d.ts

@@ -0,0 +1,201 @@
+import { z } from 'zod';
+
+declare const permissionSeedMarker: "__btst.authorization.permission-seed.v1";
+declare const permissionDescriptorMarker: "__btst.authorization.permission-descriptor.v1";
+declare const permissionCatalogMarker: "__btst.authorization.permission-catalog.v1";
+declare const authorizationContractTypes: "__btst.authorization.contract-types.v1";
+type AnySchema = z.ZodType<any, any>;
+/** A permission declaration before its stable catalog id has been assigned. */
+interface PermissionSeed<TSchema extends AnySchema | undefined> {
+    readonly [permissionSeedMarker]: true;
+    readonly schema: TSchema;
+}
+type PermissionFacts<TSchema extends AnySchema | undefined> = TSchema extends AnySchema ? z.output<TSchema> : undefined;
+type PermissionInput<TSchema extends AnySchema | undefined> = TSchema extends AnySchema ? [facts: z.input<TSchema>] : [];
+/** A validated permission request passed to client and server evaluators. */
+interface PermissionRequest<TId extends string = string, TSchema extends AnySchema | undefined = AnySchema | undefined> {
+    readonly id: TId;
+    readonly permission: PermissionDescriptor<TId, TSchema>;
+    readonly facts: PermissionFacts<TSchema>;
+}
+/** A stable, callable permission descriptor produced by `definePermissions`. */
+interface PermissionDescriptor<TId extends string = string, TSchema extends AnySchema | undefined = AnySchema | undefined> {
+    (...args: PermissionInput<TSchema>): PermissionRequest<TId, TSchema>;
+    readonly id: TId;
+    readonly schema: TSchema;
+    readonly [permissionDescriptorMarker]: true;
+}
+type PermissionTree = {
+    readonly [key: string]: PermissionTree | PermissionSeed<AnySchema | undefined>;
+};
+type AppendPath<TPath extends string, TKey extends string> = TPath extends "" ? TKey : `${TPath}.${TKey}`;
+type BoundPermissionTree<TTree, TNamespace extends string, TPath extends string = ""> = TTree extends PermissionSeed<infer TSchema> ? PermissionDescriptor<`${TNamespace}:${TPath}`, TSchema> : {
+    readonly [TKey in keyof TTree]: TKey extends string ? BoundPermissionTree<TTree[TKey], TNamespace, AppendPath<TPath, TKey>> : never;
+};
+/** A named catalog of permission descriptors. */
+type PermissionCatalog<TName extends string = string, TTree extends PermissionTree = {}> = BoundPermissionTree<TTree, TName> & {
+    readonly [permissionCatalogMarker]: {
+        readonly name: TName;
+    };
+};
+type AnyPermissionCatalog = PermissionCatalog<string>;
+/** Any schema-backed permission descriptor, for generic plugin APIs. */
+type AnyPermissionDescriptor = PermissionDescriptor<string, AnySchema | undefined>;
+type AnyPermissionRequest = PermissionRequest<string, AnySchema | undefined>;
+/** Declare a permission whose checks do not need record facts. */
+declare function permission(): PermissionSeed<undefined>;
+/** Declare a permission whose fact type is inferred from its runtime schema. */
+declare function permission<TSchema extends AnySchema>(schema: TSchema): PermissionSeed<TSchema>;
+/**
+ * Assign stable ids to a plugin's schema-backed permission declarations.
+ * The returned tree is safe to import from both browser and server modules.
+ */
+declare function definePermissions<const TName extends string, const TTree extends PermissionTree>(name: TName, tree: TTree): PermissionCatalog<TName, TTree>;
+type DescriptorsIn<T> = T extends AnyPermissionDescriptor ? T : T extends object ? {
+    [TKey in keyof T]: TKey extends typeof permissionCatalogMarker ? never : DescriptorsIn<T[TKey]>;
+}[keyof T] : never;
+type RegisteredDescriptor<TCatalogs extends readonly AnyPermissionCatalog[]> = DescriptorsIn<TCatalogs[number]>;
+type RequestFor<TDescriptor> = TDescriptor extends PermissionDescriptor<infer TId, infer TSchema> ? PermissionRequest<TId, TSchema> : never;
+/** Infer validated fact output for a permission descriptor. */
+type PermissionFactsFor<TPermission> = TPermission extends PermissionDescriptor<infer _TId, infer TSchema> ? PermissionFacts<TSchema> : never;
+/** Infer accepted fact input for a permission descriptor. */
+type PermissionInputFor<TPermission> = TPermission extends PermissionDescriptor<infer _TId, infer TSchema> ? TSchema extends AnySchema ? z.input<TSchema> : undefined : never;
+/** Infer the validated request created by a permission descriptor. */
+type PermissionRequestFor<TPermission> = RequestFor<TPermission>;
+interface AuthorizationRuleDefinition {
+    readonly permission: AnyPermissionDescriptor;
+    readonly evaluate: (input: {
+        identity: unknown;
+        facts: unknown;
+    }) => boolean;
+}
+type RulePermission<TPermission, TIdentity> = TPermission extends PermissionDescriptor<infer _TId, infer TSchema> ? {
+    allow: () => AuthorizationRuleDefinition;
+    when: (rule: (input: {
+        identity: TIdentity | null;
+        facts: PermissionFacts<TSchema>;
+    }) => boolean) => AuthorizationRuleDefinition;
+} : never;
+type RuleTree<TTree, TIdentity> = TTree extends AnyPermissionDescriptor ? RulePermission<TTree, TIdentity> : TTree extends object ? {
+    [TKey in keyof TTree as TKey extends typeof permissionCatalogMarker ? never : TKey]: RuleTree<TTree[TKey], TIdentity>;
+} : never;
+type CatalogRuleEntry<TCatalog, TIdentity> = TCatalog extends PermissionCatalog<infer TName, infer _TTree> ? {
+    [TKey in TName]: RuleTree<TCatalog, TIdentity>;
+} : never;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+type RuleCatalogs<TCatalogs extends readonly AnyPermissionCatalog[], TIdentity> = UnionToIntersection<CatalogRuleEntry<TCatalogs[number], TIdentity>>;
+/**
+ * A rule-free authorization vocabulary that can be published independently of
+ * an application's backend implementation.
+ */
+interface AuthorizationContract<TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, TCatalogs extends readonly AnyPermissionCatalog[]> {
+    readonly [authorizationContractTypes]?: {
+        readonly identity: z.output<TIdentitySchema>;
+        readonly identityInput: z.input<TIdentitySchema>;
+        readonly permission: RequestFor<RegisteredDescriptor<TCatalogs>>;
+    };
+    readonly identitySchema: TIdentitySchema;
+    readonly permissions: TCatalogs;
+    readonly permissionIds: readonly string[];
+    readonly version: string;
+    parseIdentity(identity: unknown): z.output<TIdentitySchema> | null;
+    parsePermission(permission: unknown): RequestFor<RegisteredDescriptor<TCatalogs>>;
+}
+/** Any portable authorization contract, for generic adapter APIs. */
+interface AnyAuthorizationContract {
+    readonly [authorizationContractTypes]?: {
+        readonly identity: {
+            id: string;
+        };
+        readonly identityInput: unknown;
+        readonly permission: any;
+    };
+    readonly identitySchema: z.ZodType<{
+        id: string;
+    }, any>;
+    readonly permissions: readonly AnyPermissionCatalog[];
+    readonly permissionIds: readonly string[];
+    readonly version: string;
+    parseIdentity(identity: unknown): {
+        id: string;
+    } | null;
+    parsePermission(permission: unknown): any;
+}
+type ContractIdentitySchema<TContract extends AnyAuthorizationContract> = TContract extends AuthorizationContract<infer TSchema, any> ? TSchema : never;
+type ContractCatalogs<TContract extends AnyAuthorizationContract> = TContract extends AuthorizationContract<any, infer TCatalogs> ? TCatalogs : never;
+/** Infer validated identity output from a portable contract. */
+type AuthorizationContractIdentity<TContract> = TContract extends AnyAuthorizationContract ? NonNullable<TContract[typeof authorizationContractTypes]>["identity"] : never;
+/** Infer accepted identity input from a portable contract. */
+type AuthorizationContractIdentityInput<TContract> = TContract extends AnyAuthorizationContract ? NonNullable<TContract[typeof authorizationContractTypes]>["identityInput"] : never;
+/** Infer registered permission requests from a portable contract. */
+type AuthorizationContractPermissionRequest<TContract> = TContract extends AnyAuthorizationContract ? NonNullable<TContract[typeof authorizationContractTypes]>["permission"] : never;
+/** Define a versioned identity and permission vocabulary without any rules. */
+declare function defineAuthorizationContract<const TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, const TCatalogs extends readonly AnyPermissionCatalog[]>(config: {
+    identity: TIdentitySchema;
+    permissions: TCatalogs;
+}): AuthorizationContract<TIdentitySchema, TCatalogs>;
+/** The shared, synchronous authorization contract used by client and server. */
+interface Authorization<TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, TCatalogs extends readonly AnyPermissionCatalog[]> {
+    readonly contract: AuthorizationContract<TIdentitySchema, TCatalogs>;
+    readonly identitySchema: TIdentitySchema;
+    readonly permissions: TCatalogs;
+    parseIdentity(identity: unknown): z.output<TIdentitySchema> | null;
+    can(request: RequestFor<RegisteredDescriptor<TCatalogs>>, identity: z.input<TIdentitySchema> | null): boolean;
+}
+/** Any one-rule authorization contract, for generic adapter APIs. */
+interface AnyAuthorization {
+    readonly contract: AnyAuthorizationContract;
+    readonly identitySchema: z.ZodType<{
+        id: string;
+    }, any>;
+    readonly permissions: readonly AnyPermissionCatalog[];
+    parseIdentity(identity: unknown): {
+        id: string;
+    } | null;
+    can(request: any, identity: any): boolean;
+}
+/** Infer validated identity output from an authorization contract. */
+type AuthorizationIdentity<TAuthorization> = TAuthorization extends {
+    readonly identitySchema: infer TSchema extends z.ZodType<{
+        id: string;
+    }, any>;
+} ? z.output<TSchema> : never;
+/** Infer accepted identity input from an authorization contract. */
+type AuthorizationIdentityInput<TAuthorization> = TAuthorization extends {
+    readonly identitySchema: infer TSchema extends z.ZodType<{
+        id: string;
+    }, any>;
+} ? z.input<TSchema> : never;
+/** Infer registered permission requests from an authorization contract. */
+type AuthorizationPermissionRequest<TAuthorization> = TAuthorization extends {
+    readonly permissions: infer TCatalogs extends readonly AnyPermissionCatalog[];
+} ? RequestFor<RegisteredDescriptor<TCatalogs>> : never;
+/** Infer stable permission ids registered by an authorization contract. */
+type AuthorizationPermissionId<TAuthorization> = TAuthorization extends Authorization<any, infer TCatalogs> ? RegisteredDescriptor<TCatalogs> extends PermissionDescriptor<infer TId, any> ? TId : never : never;
+/**
+ * Define one browser-safe rule set over a validated identity and registered
+ * permission catalogs. Missing rules deny; rule failures are allowed to
+ * propagate so outages never masquerade as ordinary denials.
+ */
+declare function defineAuthorization<const TContract extends AnyAuthorizationContract>(config: {
+    contract: TContract;
+    rules: (permissions: RuleCatalogs<ContractCatalogs<TContract>, z.output<ContractIdentitySchema<TContract>>>) => readonly AuthorizationRuleDefinition[];
+}): Authorization<ContractIdentitySchema<TContract>, ContractCatalogs<TContract>>;
+declare function defineAuthorization<const TIdentitySchema extends z.ZodType<{
+    id: string;
+}, any>, const TCatalogs extends readonly AnyPermissionCatalog[]>(config: {
+    identity: TIdentitySchema;
+    permissions: TCatalogs;
+    rules: (permissions: RuleCatalogs<TCatalogs, z.output<TIdentitySchema>>) => readonly AuthorizationRuleDefinition[];
+}): Authorization<TIdentitySchema, TCatalogs>;
+/** Check whether a runtime value has the shape of a permission request. */
+declare function isPermissionRequest(value: unknown): value is AnyPermissionRequest;
+
+export { defineAuthorization, defineAuthorizationContract, definePermissions, isPermissionRequest, permission };
+export type { AnyAuthorization, AnyAuthorizationContract, AnyPermissionDescriptor, Authorization, AuthorizationContract, AuthorizationContractIdentity, AuthorizationContractIdentityInput, AuthorizationContractPermissionRequest, AuthorizationIdentity, AuthorizationIdentityInput, AuthorizationPermissionId, AuthorizationPermissionRequest, PermissionCatalog, PermissionDescriptor, PermissionFactsFor, PermissionInputFor, PermissionRequest, PermissionRequestFor, PermissionSeed };