@forgezero/access 0.1.13 → 0.1.15

package/dist/principal.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.13";
+var VERSION = "0.1.15";
 
 // src/principal.ts
 var ATOM = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;

package/dist/schema.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Dependency-free JSON-Schema SSOT primitives for request and response
+ * boundaries. A contract is declared once as data and its TypeScript type is
+ * inferred from that same value; consumers must not repeat the wire shape in
+ * an interface or type alias.
+ */
+declare const contractType: unique symbol;
+declare const optionalProperty: unique symbol;
+export type ContractSchema<Value = unknown> = Readonly<Record<string, unknown>> & {
+    readonly [contractType]?: Value;
+};
+export type Infer<Schema extends ContractSchema> = Schema extends ContractSchema<infer Value> ? Value : never;
+export type OptionalSchema<Schema extends ContractSchema> = Schema & {
+    readonly [optionalProperty]: true;
+};
+type PropertyValue<Schema extends ContractSchema> = Infer<Schema>;
+type RequiredPropertyKeys<Properties extends Readonly<Record<string, ContractSchema>>> = {
+    [Key in keyof Properties]-?: Properties[Key] extends OptionalSchema<ContractSchema> ? never : Key;
+}[keyof Properties];
+type OptionalPropertyKeys<Properties extends Readonly<Record<string, ContractSchema>>> = Exclude<keyof Properties, RequiredPropertyKeys<Properties>>;
+type ObjectValue<Properties extends Readonly<Record<string, ContractSchema>>> = {
+    [Key in RequiredPropertyKeys<Properties>]: PropertyValue<Properties[Key]>;
+} & {
+    [Key in OptionalPropertyKeys<Properties>]?: PropertyValue<Properties[Key]>;
+};
+export type ContractIssue = Readonly<{
+    path: string;
+    expected: string;
+}>;
+export type ContractParseResult<Value> = Readonly<{
+    ok: true;
+    value: Value;
+}> | Readonly<{
+    ok: false;
+    issues: readonly ContractIssue[];
+}>;
+type StringOptions = Readonly<{
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+}>;
+type NumberOptions = Readonly<{
+    minimum?: number;
+    maximum?: number;
+}>;
+type ArrayOptions = Readonly<{
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+}>;
+type ObjectOptions = Readonly<{
+    additionalProperties?: boolean;
+}>;
+type RecordOptions = Readonly<{
+    minProperties?: number;
+    maxProperties?: number;
+    keyPattern?: string;
+}>;
+export declare const schema: Readonly<{
+    unknown: () => ContractSchema<unknown>;
+    string: (options?: StringOptions) => ContractSchema<string>;
+    number: (options?: NumberOptions) => ContractSchema<number>;
+    integer: (options?: NumberOptions) => ContractSchema<number>;
+    boolean: () => ContractSchema<boolean>;
+    null: () => ContractSchema<null>;
+    literal: <const Value extends string | number | boolean | null>(value: Value) => ContractSchema<Value>;
+    optional: <Schema extends ContractSchema>(value: Schema) => OptionalSchema<Schema>;
+    array: <Schema extends ContractSchema>(items: Schema, options?: ArrayOptions) => ContractSchema<Array<Infer<Schema>>>;
+    union: <const Schemas extends readonly ContractSchema[]>(...members: Schemas) => ContractSchema<Infer<Schemas[number]>>;
+    object: <const Properties extends Readonly<Record<string, ContractSchema>>>(properties: Properties, options?: ObjectOptions) => ContractSchema<ObjectValue<Properties>>;
+    record: <Schema extends ContractSchema>(values: Schema, options?: RecordOptions) => ContractSchema<Record<string, Infer<Schema>>>;
+}>;
+export declare function extend<Base extends ContractSchema<Record<string, unknown>>, Extension extends ContractSchema<Record<string, unknown>>>(base: Base, extension: Extension): ContractSchema<Infer<Base> & Infer<Extension>>;
+export declare function pick<Source extends ContractSchema<Record<string, unknown>>, const Keys extends readonly (keyof Infer<Source> & string)[]>(source: Source, keys: Keys): ContractSchema<Pick<Infer<Source>, Keys[number]>>;
+export declare function omit<Source extends ContractSchema<Record<string, unknown>>, const Keys extends readonly (keyof Infer<Source> & string)[]>(source: Source, keys: Keys): ContractSchema<Omit<Infer<Source>, Keys[number]>>;
+export declare function parse<Schema extends ContractSchema>(contract: Schema, value: unknown): ContractParseResult<Infer<Schema>>;
+export {};

package/dist/schema.js

@@ -0,0 +1,171 @@
+// src/schema.ts
+var contractType = Symbol("forgezero.contract.type");
+var optionalProperty = Symbol("forgezero.contract.optional");
+function freeze(schema) {
+  return Object.freeze(schema);
+}
+var schema = Object.freeze({
+  unknown: () => freeze({}),
+  string: (options = {}) => freeze({ type: "string", ...options }),
+  number: (options = {}) => freeze({ type: "number", ...options }),
+  integer: (options = {}) => freeze({ type: "integer", ...options }),
+  boolean: () => freeze({ type: "boolean" }),
+  null: () => freeze({ type: "null" }),
+  literal: (value) => freeze({ const: value }),
+  optional: (value) => Object.freeze({ ...value, [optionalProperty]: true }),
+  array: (items, options = {}) => freeze({ type: "array", items, ...options }),
+  union: (...members) => freeze({ anyOf: members }),
+  object: (properties, options = { additionalProperties: false }) => {
+    const required = Object.entries(properties).filter(([, value]) => !(optionalProperty in value)).map(([key]) => key);
+    const cleanProperties = Object.fromEntries(Object.entries(properties).map(([key, value]) => {
+      if (!(optionalProperty in value))
+        return [key, value];
+      const { [optionalProperty]: _, ...clean } = value;
+      return [key, clean];
+    }));
+    return freeze({ type: "object", properties: cleanProperties, required, ...options });
+  },
+  record: (values, options = {}) => freeze({
+    type: "object",
+    properties: {},
+    additionalProperties: values,
+    ...options.minProperties === undefined ? {} : { minProperties: options.minProperties },
+    ...options.maxProperties === undefined ? {} : { maxProperties: options.maxProperties },
+    ...options.keyPattern === undefined ? {} : { propertyNames: { pattern: options.keyPattern } }
+  })
+});
+function extend(base, extension) {
+  const baseProperties = base.properties ?? {};
+  const extensionProperties = extension.properties ?? {};
+  const required = [...new Set([
+    ...base.required ?? [],
+    ...extension.required ?? []
+  ])];
+  return freeze({
+    type: "object",
+    properties: { ...baseProperties, ...extensionProperties },
+    required,
+    additionalProperties: false
+  });
+}
+function pick(source, keys) {
+  const sourceProperties = source.properties ?? {};
+  const selected = Object.fromEntries(keys.map((key) => [key, sourceProperties[key]]));
+  const required = (source.required ?? []).filter((key) => keys.includes(key));
+  return freeze({ type: "object", properties: selected, required, additionalProperties: false });
+}
+function omit(source, keys) {
+  const omitted = new Set(keys);
+  const sourceProperties = source.properties ?? {};
+  const selected = Object.fromEntries(Object.entries(sourceProperties).filter(([key]) => !omitted.has(key)));
+  const required = (source.required ?? []).filter((key) => !omitted.has(key));
+  return freeze({ type: "object", properties: selected, required, additionalProperties: false });
+}
+var record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function validate(current, value, path, issues) {
+  if (issues.length >= 32)
+    return false;
+  if ("const" in current) {
+    const valid = value === current.const;
+    if (!valid)
+      issues.push({ path, expected: JSON.stringify(current.const) });
+    return valid;
+  }
+  if (Array.isArray(current.anyOf)) {
+    for (const member of current.anyOf) {
+      const candidate = [];
+      if (validate(member, value, path, candidate))
+        return true;
+    }
+    issues.push({ path, expected: "one declared union member" });
+    return false;
+  }
+  if (current.type === "string") {
+    const valid = typeof value === "string" && (typeof current.minLength !== "number" || value.length >= current.minLength) && (typeof current.maxLength !== "number" || value.length <= current.maxLength) && (typeof current.pattern !== "string" || new RegExp(current.pattern).test(value));
+    if (!valid)
+      issues.push({ path, expected: "declared string" });
+    return valid;
+  }
+  if (current.type === "number" || current.type === "integer") {
+    const valid = typeof value === "number" && Number.isFinite(value) && (current.type !== "integer" || Number.isSafeInteger(value)) && (typeof current.minimum !== "number" || value >= current.minimum) && (typeof current.maximum !== "number" || value <= current.maximum);
+    if (!valid)
+      issues.push({ path, expected: `declared ${String(current.type)}` });
+    return valid;
+  }
+  if (current.type === "boolean" || current.type === "null") {
+    const valid = current.type === "boolean" ? typeof value === "boolean" : value === null;
+    if (!valid)
+      issues.push({ path, expected: String(current.type) });
+    return valid;
+  }
+  if (current.type === "array") {
+    if (!Array.isArray(value)) {
+      issues.push({ path, expected: "array" });
+      return false;
+    }
+    let valid = (typeof current.minItems !== "number" || value.length >= current.minItems) && (typeof current.maxItems !== "number" || value.length <= current.maxItems);
+    if (current.uniqueItems === true && new Set(value.map((entry) => JSON.stringify(entry))).size !== value.length)
+      valid = false;
+    if (!valid)
+      issues.push({ path, expected: "bounded declared array" });
+    for (let index = 0;index < value.length && issues.length < 32; index += 1) {
+      valid = validate(current.items, value[index], `${path}[${index}]`, issues) && valid;
+    }
+    return valid;
+  }
+  if (current.type === "object") {
+    if (!record(value)) {
+      issues.push({ path, expected: "object" });
+      return false;
+    }
+    const properties = current.properties ?? {};
+    const required = new Set(current.required ?? []);
+    let valid = (typeof current.minProperties !== "number" || Object.keys(value).length >= current.minProperties) && (typeof current.maxProperties !== "number" || Object.keys(value).length <= current.maxProperties);
+    if (!valid)
+      issues.push({ path, expected: "bounded property count" });
+    const keyPattern = current.propertyNames?.pattern;
+    if (typeof keyPattern === "string") {
+      for (const key of Object.keys(value))
+        if (!new RegExp(keyPattern).test(key)) {
+          issues.push({ path: `${path}.${key}`, expected: "declared property name" });
+          valid = false;
+        }
+    }
+    for (const key of required) {
+      if (!(key in value)) {
+        issues.push({ path: `${path}.${key}`, expected: "required property" });
+        valid = false;
+      }
+    }
+    if (current.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(key in properties)) {
+          issues.push({ path: `${path}.${key}`, expected: "no additional property" });
+          valid = false;
+        }
+      }
+    } else if (record(current.additionalProperties)) {
+      for (const [key, child] of Object.entries(value)) {
+        if (!(key in properties))
+          valid = validate(current.additionalProperties, child, `${path}.${key}`, issues) && valid;
+      }
+    }
+    for (const [key, child] of Object.entries(properties)) {
+      if (key in value)
+        valid = validate(child, value[key], `${path}.${key}`, issues) && valid;
+    }
+    return valid;
+  }
+  return true;
+}
+function parse(contract, value) {
+  const issues = [];
+  return validate(contract, value, "$", issues) ? { ok: true, value } : { ok: false, issues };
+}
+export {
+  schema,
+  pick,
+  parse,
+  omit,
+  extend
+};

package/dist/testing.js

@@ -59,14 +59,42 @@ function defineFactors(factors) {
   }
   return factors;
 }
+var ROUTE_LIFECYCLE_STATES = ["active", "deprecated", "retired"];
 function page(label, options = {}) {
-  return { kind: "page", label, accessGroup: "default", ...options };
+  return {
+    kind: "page",
+    label,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, accessGroup: "default", ...options };
+  return {
+    kind: "action",
+    label,
+    method,
+    accessGroup: "default",
+    lifecycle: { version: 1, status: "active", introducedAt: "initial" },
+    ...options
+  };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    const lifecycle = route.lifecycle;
+    if (!Number.isSafeInteger(lifecycle.version) || lifecycle.version < 1) {
+      throw new AccessError("ROUTE_VERSION_INVALID", `"${key}": route version must be a positive integer.`);
+    }
+    const validTimestamp = (value) => Number.isFinite(Date.parse(value));
+    if (lifecycle.introducedAt !== "initial" && !validTimestamp(lifecycle.introducedAt)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": introducedAt must be an ISO timestamp or initial.`);
+    }
+    if (lifecycle.status === "deprecated" && (!validTimestamp(lifecycle.deprecatedAt) || !validTimestamp(lifecycle.expiresAt) || Date.parse(lifecycle.deprecatedAt) > Date.parse(lifecycle.expiresAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": deprecated route lifecycle is invalid.`);
+    }
+    if (lifecycle.status === "retired" && (!validTimestamp(lifecycle.retiredAt) || lifecycle.replacement === key)) {
+      throw new AccessError("ROUTE_LIFECYCLE_INVALID", `"${key}": retired route lifecycle is invalid.`);
+    }
     if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
       throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
     }
@@ -224,6 +252,10 @@ function defineAccessControl(config) {
       const route = config.routes[key];
       if (!route)
         return false;
+      if (route.lifecycle?.status === "retired")
+        return false;
+      if (route.lifecycle?.status === "deprecated" && Date.parse(context?.now ?? new Date().toISOString()) >= Date.parse(route.lifecycle.expiresAt))
+        return false;
       if (route.feature && !features.includes(route.feature))
         return false;
       if (context?.stage && route.stages && !route.stages.includes(context.stage))
@@ -275,7 +307,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.13";
+var VERSION = "0.1.15";
 
 // src/testing.ts
 function nameOf(policies, route) {

package/dist/vault.d.ts

@@ -0,0 +1,177 @@
+import { type Infer } from './schema';
+export declare const VaultDomainSchema: import("./schema").ContractSchema<"service" | "platform-authority" | "deployment">;
+export type VaultDomain = Infer<typeof VaultDomainSchema>;
+export declare const VaultEntryScopeSchema: import("./schema").ContractSchema<({
+    kind: "account";
+} & {}) | ({
+    kind: "project";
+    projectKey: string;
+} & {}) | ({
+    kind: "deployment";
+    projectKey: string;
+    deploymentKey: string;
+} & {})>;
+export type VaultEntryScope = Infer<typeof VaultEntryScopeSchema>;
+export declare const VaultAccessTargetSchema: import("./schema").ContractSchema<{
+    projectKey: string;
+} & {
+    deploymentKey?: string | null | undefined;
+}>;
+export type VaultAccessTarget = Infer<typeof VaultAccessTargetSchema>;
+export declare const DeploymentCredentialPurposeSchema: import("./schema").ContractSchema<"deployment-infrastructure" | "runtime-secret">;
+export type DeploymentCredentialPurpose = Infer<typeof DeploymentCredentialPurposeSchema>;
+export declare const DeploymentCredentialRequirementSchema: import("./schema").ContractSchema<{
+    alias: string;
+    purpose: "deployment-infrastructure" | "runtime-secret";
+    defaultEntryKey: string;
+} & {
+    schema?: string | undefined;
+}>;
+export type DeploymentCredentialRequirement = Infer<typeof DeploymentCredentialRequirementSchema>;
+/** Exact opaque deployment binding. It contains no secret value. */
+export declare const DeploymentVaultBindingSchema: import("./schema").ContractSchema<{
+    schema: string;
+    projectKey: string;
+    deploymentKey: string;
+    alias: string;
+    purpose: "deployment-infrastructure" | "runtime-secret";
+    vaultEntryRef: string;
+    environmentKey: string;
+    entryKey: string;
+} & {}>;
+export type DeploymentVaultBinding = Infer<typeof DeploymentVaultBindingSchema>;
+export declare const DeploymentVaultBindingsSchema: import("./schema").ContractSchema<Record<string, {
+    schema: string;
+    projectKey: string;
+    deploymentKey: string;
+    alias: string;
+    purpose: "deployment-infrastructure" | "runtime-secret";
+    vaultEntryRef: string;
+    environmentKey: string;
+    entryKey: string;
+} & {}>>;
+export type DeploymentVaultBindings = Infer<typeof DeploymentVaultBindingsSchema>;
+export declare const DeploymentVaultEntryTypeSchema: import("./schema").ContractSchema<"text" | "secret" | "json">;
+export type DeploymentVaultEntryType = Infer<typeof DeploymentVaultEntryTypeSchema>;
+/**
+ * A checked-in schema accepts its declared structured value. When the plan has
+ * no dedicated form schema, the manual variants remain deliberately small and
+ * map to the built-in Text/Secret catalogue.
+ */
+export declare const DeploymentVaultEntryInputSchema: import("./schema").ContractSchema<({
+    projectKey: string;
+    deploymentKey: string;
+    environmentKey: string;
+    entryKey: string;
+} & {
+    schema?: string | undefined;
+    description?: string | undefined;
+} & {
+    value: string;
+    entryType: "text";
+} & {}) | ({
+    projectKey: string;
+    deploymentKey: string;
+    environmentKey: string;
+    entryKey: string;
+} & {
+    schema?: string | undefined;
+    description?: string | undefined;
+} & {
+    value: string;
+    entryType: "secret";
+} & {}) | ({
+    projectKey: string;
+    deploymentKey: string;
+    environmentKey: string;
+    entryKey: string;
+} & {
+    schema?: string | undefined;
+    description?: string | undefined;
+} & {
+    value: string;
+    entryType: "json";
+} & {}) | ({
+    projectKey: string;
+    deploymentKey: string;
+    environmentKey: string;
+    entryKey: string;
+} & {
+    schema?: string | undefined;
+    description?: string | undefined;
+} & {
+    value: unknown;
+    schema: string;
+} & {})>;
+export type DeploymentVaultEntryInput = Infer<typeof DeploymentVaultEntryInputSchema>;
+export declare const PipelineVaultBindRequestSchema: import("./schema").ContractSchema<{
+    alias: string;
+    environmentKey: string;
+    entryKey: string;
+    pipelineKey: string;
+} & {}>;
+export type PipelineVaultBindRequest = Infer<typeof PipelineVaultBindRequestSchema>;
+export declare const PipelineVaultUnbindRequestSchema: import("./schema").ContractSchema<{
+    alias: string;
+    pipelineKey: string;
+} & {}>;
+export type PipelineVaultUnbindRequest = Infer<typeof PipelineVaultUnbindRequestSchema>;
+export declare const DeploymentVaultCreateAndBindRequestSchema: import("./schema").ContractSchema<{
+    entry: ({
+        projectKey: string;
+        deploymentKey: string;
+        environmentKey: string;
+        entryKey: string;
+    } & {
+        schema?: string | undefined;
+        description?: string | undefined;
+    } & {
+        value: string;
+        entryType: "text";
+    } & {}) | ({
+        projectKey: string;
+        deploymentKey: string;
+        environmentKey: string;
+        entryKey: string;
+    } & {
+        schema?: string | undefined;
+        description?: string | undefined;
+    } & {
+        value: string;
+        entryType: "secret";
+    } & {}) | ({
+        projectKey: string;
+        deploymentKey: string;
+        environmentKey: string;
+        entryKey: string;
+    } & {
+        schema?: string | undefined;
+        description?: string | undefined;
+    } & {
+        value: string;
+        entryType: "json";
+    } & {}) | ({
+        projectKey: string;
+        deploymentKey: string;
+        environmentKey: string;
+        entryKey: string;
+    } & {
+        schema?: string | undefined;
+        description?: string | undefined;
+    } & {
+        value: unknown;
+        schema: string;
+    } & {});
+    alias: string;
+    pipelineKey: string;
+} & {}>;
+export type DeploymentVaultCreateAndBindRequest = Infer<typeof DeploymentVaultCreateAndBindRequestSchema>;
+export declare function validVaultEntryScope(value: unknown): value is VaultEntryScope;
+/** Human selection may bind a reusable service entry explicitly. */
+export declare function vaultScopeAllows(scope: VaultEntryScope, target: VaultAccessTarget): boolean;
+/** Agent access never inherits account/project wildcard access. */
+export declare function deploymentBindingAllows(binding: DeploymentVaultBinding, target: {
+    projectKey: string;
+    deploymentKey: string;
+    alias: string;
+}): boolean;