@fungi.computer/oyster 0.0.1 → 0.2.0

package/docs/api/tenancy/resolve.md

@@ -0,0 +1,69 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](../README.md)
+
+---
+
+[@fungi.computer/oyster](../modules.md) / tenancy/resolve
+
+# tenancy/resolve
+
+## Functions
+
+### subdomain()
+
+```ts
+function subdomain(baseDomain): TenantResolverAdapter<"origin">;
+```
+
+Resolve a provisioned label immediately below a configured base hostname.
+
+#### Parameters
+
+| Parameter    | Type     |
+| ------------ | -------- |
+| `baseDomain` | `string` |
+
+#### Returns
+
+[`TenantResolverAdapter`](../tenancy.md#tenantresolveradapter)\<`"origin"`\>
+
+---
+
+### hosts()
+
+```ts
+function hosts(registry): TenantResolverAdapter<"origin">;
+```
+
+Resolve a provisioned custom domain through the registry's domain index.
+
+#### Parameters
+
+| Parameter  | Type                                                             |
+| ---------- | ---------------------------------------------------------------- |
+| `registry` | [`ReadonlyTenantRegistry`](../tenancy.md#readonlytenantregistry) |
+
+#### Returns
+
+[`TenantResolverAdapter`](../tenancy.md#tenantresolveradapter)\<`"origin"`\>
+
+---
+
+### path()
+
+```ts
+function path(pattern): TenantResolverAdapter<"path">;
+```
+
+Resolve provisioned path tenants for APIs; this resolver cannot host Oyster.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `pattern` | `string` |
+
+#### Returns
+
+[`TenantResolverAdapter`](../tenancy.md#tenantresolveradapter)\<`"path"`\>

package/docs/api/tenancy.md

@@ -0,0 +1,430 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / tenancy
+
+# tenancy
+
+## Type Aliases
+
+### Identity
+
+```ts
+type Identity = Readonly<{
+  provider: string;
+  subject: string;
+  email?: string;
+}>;
+```
+
+An external identity; the registry owns its canonical member mapping.
+
+---
+
+### Tenant
+
+```ts
+type Tenant = Readonly<{
+  id: TenantId;
+  handle: string;
+  origin: string;
+  status: "active" | "suspended" | "deleting";
+  owners: readonly string[];
+  domains: readonly string[];
+}>;
+```
+
+One provisioned tenant and its registry-owned canonical public origin.
+
+---
+
+### Membership
+
+```ts
+type Membership = Readonly<{
+  memberId: string;
+  role: "owner" | "member";
+  membershipVersion: number;
+}>;
+```
+
+A live membership, carrying a stored host-owned member identity.
+
+---
+
+### ReadonlyTenantRegistry
+
+```ts
+type ReadonlyTenantRegistry = Readonly<{
+  get: Promise<Readonly<{
+    id: TenantId;
+    handle: string;
+    origin: string;
+    status: "active" | "suspended" | "deleting";
+    owners: readonly string[];
+    domains: readonly string[];
+  }> | null>;
+  byHandle: Promise<Readonly<{
+    id: TenantId;
+    handle: string;
+    origin: string;
+    status: "active" | "suspended" | "deleting";
+    owners: readonly string[];
+    domains: readonly string[];
+  }> | null>;
+  byDomain?: Promise<Readonly<{
+    id: TenantId;
+    handle: string;
+    origin: string;
+    status: "active" | "suspended" | "deleting";
+    owners: readonly string[];
+    domains: readonly string[];
+  }> | null>;
+  status: Promise<"active" | "deleting" | "suspended" | null>;
+  membershipOf: Promise<Readonly<{
+    memberId: string;
+    role: "owner" | "member";
+    membershipVersion: number;
+  }> | null>;
+  memberById: Promise<Readonly<{
+    memberId: string;
+    role: "owner" | "member";
+    membershipVersion: number;
+  }> | null>;
+}>;
+```
+
+Reads existing authority; this port cannot mutate tenants or members.
+
+---
+
+### TenantCreateInput
+
+```ts
+type TenantCreateInput = Readonly<{
+  handle: string;
+  origin: string;
+  domains: readonly string[];
+  owner: Identity;
+}>;
+```
+
+A single create transition records tenant and owner membership together.
+
+---
+
+### ManagedTenantRegistry
+
+```ts
+type ManagedTenantRegistry = ReadonlyTenantRegistry &
+  Readonly<{
+    create: Promise<
+      Readonly<{
+        id: TenantId;
+        handle: string;
+        origin: string;
+        status: "active" | "suspended" | "deleting";
+        owners: readonly string[];
+        domains: readonly string[];
+      }>
+    >;
+    setStatus: Promise<void>;
+    delete: Promise<void>;
+  }>;
+```
+
+Mutable registry owner; remove is called only after teardown succeeds.
+
+---
+
+### TenantResolverAdapter
+
+```ts
+type TenantResolverAdapter<Kind> = Readonly<{
+  kind: Kind;
+  resolve: Promise<(string & Brand<"OysterTenantId">) | null>;
+}>;
+```
+
+Request URL resolution, with an explicit origin/path distinction.
+
+#### Type Parameters
+
+| Type Parameter                          | Default type           |
+| --------------------------------------- | ---------------------- |
+| `Kind` _extends_ `"origin"` \| `"path"` | `"origin"` \| `"path"` |
+
+---
+
+### AuthResult
+
+```ts
+type AuthResult =
+  | Readonly<{
+      kind: "identity";
+      identity: Identity;
+    }>
+  | Readonly<{
+      kind: "principal";
+      principal: TenantPrincipal;
+    }>
+  | Readonly<{
+      kind: "pass";
+    }>
+  | Readonly<{
+      kind: "refused";
+      status: 401 | 403;
+    }>;
+```
+
+Adapter output: pass only when the presented credential is not this adapter's.
+
+---
+
+### AuthAdapter
+
+```ts
+type AuthAdapter = Readonly<{
+  id: string;
+  routes?: Hono;
+  authenticate: Promise<AuthResult>;
+}>;
+```
+
+Authentication proves an identity, or attests a principal for this tenant.
+
+---
+
+### TenancyPolicy
+
+```ts
+type TenancyPolicy = (context) => Promise<
+  | Readonly<{
+      kind: "allow";
+    }>
+  | Readonly<{
+      kind: "refuse";
+      status: 429;
+      retryAfter: number;
+    }>
+>;
+```
+
+Abuse-only admission policy; it does not meter or bill usage.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                  |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `context` | `Readonly`\<\{ `tenant`: [`Tenant`](#tenant); `principal`: [`TenantPrincipal`](tenant.md#tenantprincipal); `request`: `Request`; \}\> |
+
+#### Returns
+
+`Promise`\< \| `Readonly`\<\{ `kind`: `"allow"`; \}\> \| `Readonly`\<\{ `kind`:
+`"refuse"`; `status`: `429`; `retryAfter`: `number`; \}\>\>
+
+---
+
+### TenancyHooks
+
+```ts
+type TenancyHooks = Readonly<{
+  tenant.created?: (context) => Promise<void>;
+  tenant.deleting?: (context) => Promise<void>;
+}>;
+```
+
+Lifecycle callbacks run after create and before physical deletion.
+
+---
+
+### TenancyAdmission
+
+```ts
+type TenancyAdmission =
+  | Readonly<{
+      kind: "admitted";
+      tenant: Tenant;
+      principal: TenantPrincipal;
+    }>
+  | Readonly<{
+      kind: "refused";
+      status: 401 | 403 | 404 | 429;
+      retryAfter?: number;
+    }>;
+```
+
+Typed result of tenant authentication and abuse-policy admission.
+
+---
+
+### TenancyVariables
+
+```ts
+type TenancyVariables = object;
+```
+
+Typed Hono context fields populated only after admission.
+
+#### Properties
+
+##### tenant
+
+```ts
+tenant: Tenant;
+```
+
+The admitted provisioned tenant.
+
+##### principal
+
+```ts
+principal: TenantPrincipal;
+```
+
+The admitted canonical principal.
+
+---
+
+### ReadonlyTenancy
+
+```ts
+type ReadonlyTenancy<Kind> = Readonly<{
+  resolve: Promise<Readonly<{
+    id: TenantId;
+    handle: string;
+    origin: string;
+    status: "active" | "suspended" | "deleting";
+    owners: readonly string[];
+    domains: readonly string[];
+  }> | null>;
+  authenticate: Promise<TenancyAdmission>;
+  member: Promise<TenantPrincipal | null>;
+  memberById: Promise<
+    (TenantPrincipal & Readonly<{ membershipVersion: number }>) | null
+  >;
+  middleware: MiddlewareHandler<{
+    Variables: TenancyVariables;
+  }>;
+}> &
+  Kind extends "origin"
+  ? Readonly<{
+      oyster: OysterTenancy;
+    }>
+  : Record<never, never>;
+```
+
+Read-only host API; no create/delete methods are exposed.
+
+#### Type Parameters
+
+| Type Parameter                          | Default type           |
+| --------------------------------------- | ---------------------- |
+| `Kind` _extends_ `"origin"` \| `"path"` | `"origin"` \| `"path"` |
+
+---
+
+### ManagedTenancy
+
+```ts
+type ManagedTenancy<Kind> = ReadonlyTenancy<Kind> &
+  Readonly<{
+    create: Promise<
+      Readonly<{
+        id: TenantId;
+        handle: string;
+        origin: string;
+        status: "active" | "suspended" | "deleting";
+        owners: readonly string[];
+        domains: readonly string[];
+      }>
+    >;
+    delete: Promise<void>;
+  }>;
+```
+
+Managed hosts can provision tenants and run teardown through the kit.
+
+#### Type Parameters
+
+| Type Parameter                          | Default type           |
+| --------------------------------------- | ---------------------- |
+| `Kind` _extends_ `"origin"` \| `"path"` | `"origin"` \| `"path"` |
+
+---
+
+### TenancyConfig
+
+```ts
+type TenancyConfig<Registry, Kind> = Readonly<{
+  resolve: TenantResolverAdapter<Kind>;
+  registry: Registry;
+  auth: readonly AuthAdapter[];
+  policy?: TenancyPolicy;
+  on?: TenancyHooks;
+}>;
+```
+
+Configuration composes resolution, live registry authority and auth adapters.
+
+#### Type Parameters
+
+| Type Parameter                                                           | Default type                                        |
+| ------------------------------------------------------------------------ | --------------------------------------------------- |
+| `Registry` _extends_ [`ReadonlyTenantRegistry`](#readonlytenantregistry) | [`ReadonlyTenantRegistry`](#readonlytenantregistry) |
+| `Kind` _extends_ `"origin"` \| `"path"`                                  | `"origin"` \| `"path"`                              |
+
+## Functions
+
+### createTenancy()
+
+#### Call Signature
+
+```ts
+function createTenancy<Kind>(config): ManagedTenancy<Kind>;
+```
+
+Managed registries expose provisioning and cleanup; readonly registries do not.
+
+##### Type Parameters
+
+| Type Parameter                          |
+| --------------------------------------- |
+| `Kind` _extends_ `"path"` \| `"origin"` |
+
+##### Parameters
+
+| Parameter | Type                                                                                           |
+| --------- | ---------------------------------------------------------------------------------------------- |
+| `config`  | [`TenancyConfig`](#tenancyconfig)\<[`ManagedTenantRegistry`](#managedtenantregistry), `Kind`\> |
+
+##### Returns
+
+[`ManagedTenancy`](#managedtenancy)\<`Kind`\>
+
+#### Call Signature
+
+```ts
+function createTenancy<Kind>(config): ReadonlyTenancy<Kind>;
+```
+
+Resolve and authenticate requests without exposing registry mutations.
+
+##### Type Parameters
+
+| Type Parameter                          |
+| --------------------------------------- |
+| `Kind` _extends_ `"path"` \| `"origin"` |
+
+##### Parameters
+
+| Parameter | Type                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------ |
+| `config`  | [`TenancyConfig`](#tenancyconfig)\<[`ReadonlyTenantRegistry`](#readonlytenantregistry), `Kind`\> |
+
+##### Returns
+
+[`ReadonlyTenancy`](#readonlytenancy)\<`Kind`\>