@beignet/core 0.0.1 → 0.0.3

package/src/ports/policy.ts

@@ -1,9 +1,18 @@
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * A policy decision that allows the requested ability.
+ */
 export type GateAllowedDecision = {
   allowed: true;
 };
 
+/**
+ * A policy decision that denies the requested ability.
+ *
+ * Use `reason`, `code`, and `details` to preserve structured denial context for
+ * errors, audit logs, and tests.
+ */
 export type GateDeniedDecision = {
   allowed: false;
   reason?: string;
@@ -11,13 +20,33 @@ export type GateDeniedDecision = {
   details?: unknown;
 };
 
+/**
+ * Normalized authorization decision returned by gate inspection.
+ */
 export type GateDecision = GateAllowedDecision | GateDeniedDecision;
+
+/**
+ * Value a policy resolver may return.
+ *
+ * Returning `true`/`false` is convenient for simple policies. Return
+ * `allow()`/`deny(...)` when the caller needs a denial reason, code, or
+ * structured details.
+ */
 export type GatePolicyResult = boolean | GateDecision;
 
+/**
+ * Function that decides whether a context can perform an ability.
+ *
+ * The first argument is always the application context. Policies that operate
+ * on a record receive that record as their second argument.
+ */
 export type PolicyResolver = (
   ...args: never[]
 ) => MaybePromise<GatePolicyResult>;
 
+/**
+ * Typed collection of ability resolvers created by `definePolicy(...)`.
+ */
 export type PolicyDefinition<
   TPolicies extends Record<string, PolicyResolver> = Record<
     string,
@@ -27,6 +56,9 @@ export type PolicyDefinition<
   policies: TPolicies;
 };
 
+/**
+ * Infer the application context type from a policy resolver.
+ */
 export type PolicyContext<TResolver> = TResolver extends (
   ctx: infer Ctx,
   ...args: never[]
@@ -34,6 +66,9 @@ export type PolicyContext<TResolver> = TResolver extends (
   ? Ctx
   : never;
 
+/**
+ * Infer whether an ability needs a subject argument.
+ */
 export type PolicySubjectArgs<TResolver> = TResolver extends (
   ...args: infer TArgs
 ) => MaybePromise<GatePolicyResult>
@@ -50,6 +85,9 @@ type UnionToIntersection<T> = (
   ? U
   : never;
 
+/**
+ * Merge the ability maps from multiple policy definitions.
+ */
 export type PolicyMapFromDefinitions<
   TPolicies extends readonly PolicyDefinition[],
 > = UnionToIntersection<
@@ -58,21 +96,40 @@ export type PolicyMapFromDefinitions<
     : never
 >;
 
+/**
+ * Infer the application context type shared by a list of policy definitions.
+ */
 export type PolicyContextFromDefinitions<
   TPolicies extends readonly PolicyDefinition[],
 > = PolicyContext<
   PolicyMapFromDefinitions<TPolicies>[keyof PolicyMapFromDefinitions<TPolicies>]
 >;
 
+/**
+ * Gate bound to a specific application context.
+ *
+ * Apps commonly attach this to request context as `ctx.gate` so use cases can
+ * call `ctx.gate.authorize("posts.update", post)` without passing `ctx` back
+ * into every authorization call.
+ */
 export type BoundGate<TPolicies extends readonly PolicyDefinition[]> = {
+  /**
+   * Return only whether the ability is allowed.
+   */
   can<TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string>(
     ability: TAbility,
     ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
   ): Promise<boolean>;
+  /**
+   * Return the full allow/deny decision without throwing.
+   */
   inspect<TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string>(
     ability: TAbility,
     ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
   ): Promise<GateDecision>;
+  /**
+   * Return an allowed decision or throw for denied abilities.
+   */
   authorize<
     TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string,
   >(
@@ -81,21 +138,40 @@ export type BoundGate<TPolicies extends readonly PolicyDefinition[]> = {
   ): Promise<GateAllowedDecision>;
 };
 
+/**
+ * App-facing authorization gate.
+ *
+ * The gate evaluates app-owned policies. It is not an authentication provider:
+ * authenticate at the HTTP boundary first, then pass the resulting actor/user
+ * data into policy context.
+ */
 export type GatePort<
   TContext,
   TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[],
 > = {
+  /**
+   * Bind this gate to a context, usually during `createContext`.
+   */
   bind(ctx: TContext): BoundGate<TPolicies>;
+  /**
+   * Return only whether the ability is allowed for a context.
+   */
   can<TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string>(
     ctx: TContext,
     ability: TAbility,
     ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
   ): Promise<boolean>;
+  /**
+   * Return the full allow/deny decision for a context without throwing.
+   */
   inspect<TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string>(
     ctx: TContext,
     ability: TAbility,
     ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
   ): Promise<GateDecision>;
+  /**
+   * Return an allowed decision or throw for denied abilities.
+   */
   authorize<
     TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string,
   >(
@@ -105,6 +181,9 @@ export type GatePort<
   ): Promise<GateAllowedDecision>;
 };
 
+/**
+ * Hook used to convert a denied decision into an application-specific error.
+ */
 export type GateDenyHandler<TContext> = (
   decision: GateDeniedDecision,
   params: {
@@ -114,14 +193,26 @@ export type GateDenyHandler<TContext> = (
   },
 ) => MaybePromise<Error | undefined>;
 
+/**
+ * Options for `createGate(...)`.
+ */
 export type CreateGateOptions<
   TContext,
   TPolicies extends readonly PolicyDefinition[],
 > = {
+  /**
+   * Policy definitions to register.
+   */
   policies: TPolicies;
+  /**
+   * Optional mapper for denied authorization decisions.
+   */
   onDeny?: GateDenyHandler<TContext>;
 };
 
+/**
+ * Default error thrown by `authorize(...)` when a policy denies access.
+ */
 export class GateAuthorizationError extends Error {
   readonly code: string;
   readonly status = 403;
@@ -135,10 +226,26 @@ export class GateAuthorizationError extends Error {
   }
 }
 
+/**
+ * Create an explicit allow decision.
+ *
+ * @returns A normalized gate decision with `allowed: true`.
+ */
 export function allow(): GateAllowedDecision {
   return { allowed: true };
 }
 
+/**
+ * Create an explicit deny decision.
+ *
+ * @example
+ * ```ts
+ * return deny("Only owners can edit this post");
+ * ```
+ *
+ * @param reasonOrDecision - Optional reason string or structured denial data.
+ * @returns A normalized gate decision with `allowed: false`.
+ */
 export function deny(
   reasonOrDecision?: string | Omit<GateDeniedDecision, "allowed">,
 ): GateDeniedDecision {
@@ -152,12 +259,38 @@ export function deny(
   };
 }
 
+/**
+ * Define a typed group of authorization policies.
+ *
+ * Keep policy definitions near the feature that owns the business rule. The
+ * returned definition is registered with `createGate(...)`.
+ *
+ * @example
+ * ```ts
+ * export const postPolicy = definePolicy({
+ *   "posts.update": (ctx, post: Post) => post.authorId === ctx.actor.id,
+ * });
+ * ```
+ *
+ * @param policies - Ability resolver map keyed by stable ability names.
+ * @returns A typed policy definition for registration with `createGate(...)`.
+ */
 export function definePolicy<
   const TPolicies extends Record<string, PolicyResolver>,
 >(policies: TPolicies): PolicyDefinition<TPolicies> {
   return { policies };
 }
 
+/**
+ * Create an authorization gate from app-owned policy definitions.
+ *
+ * Register the gate as a port, then bind it to the request/background context:
+ * `gate: ports.gate.bind(context)`. Use cases can then call
+ * `ctx.gate.authorize(...)` for business authorization.
+ *
+ * @param options - Policy definitions and optional denial mapper.
+ * @returns A gate port that can evaluate registered abilities.
+ */
 export function createGate<
   TContext,
   const TPolicies extends readonly PolicyDefinition[],

package/src/ports/rate-limit.ts

@@ -1,3 +1,6 @@
+/**
+ * Input for a single rate-limit hit.
+ */
 export interface RateLimitHitOptions {
   /**
    * Unique key for this rate limit window.
@@ -15,6 +18,9 @@ export interface RateLimitHitOptions {
   windowSec: number;
 }
 
+/**
+ * Result of recording a rate-limit hit.
+ */
 export interface RateLimitResult {
   /**
    * True when the hit is within the configured limit.
@@ -36,7 +42,16 @@ export interface RateLimitResult {
   retryAfterSeconds: number | null;
 }
 
+/**
+ * App-facing rate limiting port.
+ *
+ * Implement this with an atomic shared store such as Redis for production.
+ * Hook helpers call `hit(...)` to decide whether a request should continue.
+ */
 export interface RateLimitPort {
+  /**
+   * Record one hit for a rate-limit key and return the current decision.
+   */
   hit(options: RateLimitHitOptions): Promise<RateLimitResult>;
 }
 
@@ -55,6 +70,16 @@ function toRetryAfterSeconds(resetAt: number): number {
   return Math.max(0, Math.ceil((resetAt - Date.now()) / 1000));
 }
 
+/**
+ * Create an in-memory rate limiter for tests, examples, and single-process
+ * development.
+ *
+ * This adapter is not durable or distributed. Production apps should use a
+ * provider backed by a shared atomic store when multiple processes or regions
+ * can serve requests.
+ *
+ * @returns A rate-limit port backed by a local `Map`.
+ */
 export function createMemoryRateLimiter(): RateLimitPort {
   const windows = new Map<string, MemoryRateLimitWindow>();
 

package/src/ports/redaction.ts

@@ -1,7 +1,19 @@
+/**
+ * Default replacement used when a sensitive field is redacted.
+ */
 export const DEFAULT_REDACTED_VALUE = "[redacted]";
+/**
+ * Default replacement used when recursive redaction exceeds `maxDepth`.
+ */
 export const DEFAULT_TRUNCATED_VALUE = "[truncated]";
+/**
+ * Default replacement used when recursive redaction finds a circular object.
+ */
 export const DEFAULT_CIRCULAR_VALUE = "[circular]";
 
+/**
+ * Exact header/object keys redacted by default.
+ */
 export const DEFAULT_SENSITIVE_KEYS = [
   "authorization",
   "cookie",
@@ -14,6 +26,11 @@ export const DEFAULT_SENSITIVE_KEYS = [
   "credentials",
 ] as const;
 
+/**
+ * Key substrings redacted by default.
+ *
+ * Matching is case-insensitive.
+ */
 export const DEFAULT_SENSITIVE_KEY_TERMS = [
   "token",
   "password",
@@ -23,24 +40,66 @@ export const DEFAULT_SENSITIVE_KEY_TERMS = [
   "privatekey",
 ] as const;
 
+/**
+ * Context passed to custom redaction key decisions.
+ */
 export interface RedactionDecisionContext {
+  /**
+   * Current object/header key being evaluated.
+   */
   key: string;
+  /**
+   * Path to the current value from the root object.
+   */
   path: readonly string[];
+  /**
+   * Current value being evaluated.
+   */
   value: unknown;
 }
 
+/**
+ * Options that control recursive value and header redaction.
+ */
 export interface RedactionOptions {
+  /**
+   * Value used when a key is considered sensitive.
+   */
   replacement?: string;
+  /**
+   * Value used when recursion exceeds `maxDepth`.
+   */
   truncatedValue?: string;
+  /**
+   * Value used for circular references.
+   */
   circularValue?: string;
+  /**
+   * Maximum object/array depth to traverse before truncating.
+   */
   maxDepth?: number;
+  /**
+   * Additional exact keys to redact.
+   */
   sensitiveKeys?: readonly string[];
+  /**
+   * Additional case-insensitive key substrings to redact.
+   */
   sensitiveKeyTerms?: readonly string[];
+  /**
+   * Custom key-level redaction rule.
+   */
   shouldRedactKey?: (context: RedactionDecisionContext) => boolean;
 }
 
+/**
+ * Function that returns a redacted copy of a value.
+ */
 export type Redactor<T = unknown> = (value: T) => T;
 
+/**
+ * Header input shapes accepted by `redactHeaders(...)`.
+ */
 export type RedactableHeaders =
   | Headers
   | Iterable<readonly [string, unknown]>
@@ -50,6 +109,17 @@ function normalizeKey(key: string): string {
   return key.toLowerCase();
 }
 
+/**
+ * Return whether a key should be redacted.
+ *
+ * Checks default exact keys, default key terms, user-provided exact keys,
+ * user-provided key terms, and finally `shouldRedactKey`.
+ *
+ * @param key - Object or header key to evaluate.
+ * @param options - Optional redaction behavior.
+ * @param context - Optional path/value context for custom decisions.
+ * @returns `true` when the key should be replaced.
+ */
 export function isSensitiveKey(
   key: string,
   options: RedactionOptions = {},
@@ -148,6 +218,20 @@ function redactUnknown(
   return output;
 }
 
+/**
+ * Recursively redact a value using Beignet's default sensitive-key rules plus
+ * any custom rules in `options`.
+ *
+ * This returns a copy for objects and arrays. Primitive values are returned as
+ * is unless they are under a sensitive key. Some runtime shapes are normalized:
+ * `bigint` becomes a string, `Error` becomes a plain object with `name`,
+ * `message`, and `stack`, and class instances are copied from enumerable
+ * entries.
+ *
+ * @param value - Value to redact.
+ * @param options - Optional redaction behavior.
+ * @returns A redacted value typed as the input type for caller convenience.
+ */
 export function redactValue<T = unknown>(
   value: T,
   options: RedactionOptions = {},
@@ -176,6 +260,17 @@ function headerEntries(
   return Object.entries(headers);
 }
 
+/**
+ * Redact headers into a plain object.
+ *
+ * Sensitive header names such as `authorization`, `cookie`, and token-like keys
+ * are replaced. Non-sensitive values are passed through `redactValue(...)` so
+ * nested object values are still sanitized.
+ *
+ * @param headers - Headers object, iterable entries, or plain object.
+ * @param options - Optional redaction behavior.
+ * @returns A plain object with redacted header values.
+ */
 export function redactHeaders(
   headers: RedactableHeaders,
   options: RedactionOptions = {},
@@ -192,6 +287,12 @@ export function redactHeaders(
   return output;
 }
 
+/**
+ * Create a reusable redactor function from options.
+ *
+ * @param options - Redaction behavior to apply on each call.
+ * @returns A function that redacts values with the provided options.
+ */
 export function createRedactor<T = unknown>(
   options: RedactionOptions = {},
 ): Redactor<T> {

package/src/ports/storage.ts

@@ -1,7 +1,16 @@
+/**
+ * Object visibility understood by storage ports.
+ */
 export type StorageVisibility = "private" | "public";
 
+/**
+ * String metadata stored alongside an object.
+ */
 export type StorageMetadata = Record<string, string>;
 
+/**
+ * Body types accepted by `StoragePort.put(...)`.
+ */
 export type StorageBody =
   | string
   | ArrayBuffer
@@ -9,23 +18,63 @@ export type StorageBody =
   | Blob
   | ReadableStream<Uint8Array>;
 
+/**
+ * Options for writing an object to storage.
+ */
 export interface StoragePutOptions {
+  /**
+   * MIME content type stored with the object.
+   */
   contentType?: string;
+  /**
+   * Cache-Control value stored with the object.
+   */
   cacheControl?: string;
+  /**
+   * Provider metadata stored with the object.
+   */
   metadata?: StorageMetadata;
+  /**
+   * Whether the object may receive a public URL.
+   */
   visibility?: StorageVisibility;
 }
 
+/**
+ * Metadata for an object in storage.
+ */
 export interface StorageObject {
+  /**
+   * Object key. Keys are relative object-store paths, not filesystem paths or
+   * public URLs.
+   */
   key: string;
+  /**
+   * Object size in bytes.
+   */
   size: number;
   contentType?: string;
   cacheControl?: string;
+  /**
+   * Provider metadata stored with the object.
+   */
   metadata: StorageMetadata;
+  /**
+   * Object visibility.
+   */
   visibility: StorageVisibility;
+  /**
+   * Last modification timestamp.
+   */
   lastModified: Date;
 }
 
+/**
+ * Object metadata plus a one-shot readable body.
+ *
+ * Like Fetch response bodies, storage bodies can be consumed once. Call `get`
+ * again if you need another reader.
+ */
 export interface StorageObjectBody extends StorageObject {
   /**
    * Whether this object body has already been consumed. Like Fetch response
@@ -33,25 +82,66 @@ export interface StorageObjectBody extends StorageObject {
    * buffering them.
    */
   readonly bodyUsed: boolean;
+  /**
+   * Consume the object as a readable byte stream.
+   */
   stream(): ReadableStream<Uint8Array>;
+  /**
+   * Consume the object as bytes.
+   */
   bytes(): Promise<Uint8Array>;
+  /**
+   * Consume the object as an ArrayBuffer.
+   */
   arrayBuffer(): Promise<ArrayBuffer>;
+  /**
+   * Consume the object as UTF-8 text.
+   */
   text(): Promise<string>;
 }
 
+/**
+ * App-facing object storage port.
+ *
+ * Implement this with S3, R2, local disk, or a test adapter. Application code
+ * should depend on this interface instead of provider-specific SDKs.
+ */
 export interface StoragePort {
+  /**
+   * Store an object and return its metadata.
+   */
   put(
     key: string,
     body: StorageBody,
     options?: StoragePutOptions,
   ): Promise<StorageObject>;
+  /**
+   * Return object metadata and body, or `null` when missing.
+   */
   get(key: string): Promise<StorageObjectBody | null>;
+  /**
+   * Return object metadata without its body, or `null` when missing.
+   */
   stat(key: string): Promise<StorageObject | null>;
+  /**
+   * Delete an object.
+   *
+   * @returns `true` when the object existed.
+   */
   delete(key: string): Promise<boolean>;
+  /**
+   * Return whether an object exists.
+   */
   exists(key: string): Promise<boolean>;
+  /**
+   * Return a public URL when the object is public and the adapter can build one.
+   */
   publicUrl(key: string): Promise<string | null>;
 }
 
+/**
+ * Options for `createMemoryStorage(...)`.
+ */
 export interface MemoryStorageOptions {
   /**
    * Base URL used by `publicUrl(...)` for objects written with
@@ -219,6 +309,16 @@ function joinPublicUrl(baseUrl: string, key: string): string {
   return `${base}/${encodedKey}`;
 }
 
+/**
+ * Create an in-memory object storage adapter for tests, examples, and
+ * single-process development.
+ *
+ * This adapter validates object keys using Beignet's storage key rules. It is
+ * not durable and does not share objects across processes.
+ *
+ * @param options - Optional public URL base for public objects.
+ * @returns A storage port backed by a local `Map`.
+ */
 export function createMemoryStorage(
   options: MemoryStorageOptions = {},
 ): StoragePort {