@fungi.computer/oyster 0.0.0-stage → 0.1.0

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`\>

package/docs/api/tenant.md

@@ -0,0 +1,194 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / tenant
+
+# tenant
+
+## Type Aliases
+
+### TenantId
+
+```ts
+type TenantId = typeof tenantIdSchema.Type;
+```
+
+A validated host-selected tenant identity.
+
+---
+
+### TenantPrincipal
+
+```ts
+type TenantPrincipal =
+  | Readonly<{
+      actor: Extract<
+        HostActor,
+        {
+          kind: "member";
+        }
+      >;
+      role: "owner" | "member";
+      soleMember?: true;
+    }>
+  | Readonly<{
+      actor: Exclude<
+        HostActor,
+        {
+          kind: "member";
+        }
+      >;
+    }>;
+```
+
+A canonical host actor with a tenant role only when the actor is a member.
+
+---
+
+### TenantResolver
+
+```ts
+type TenantResolver = Readonly<{
+  resolve: Promise<Readonly<{
+    tenantId: TenantId;
+    origin: string;
+  }> | null>;
+}>;
+```
+
+Resolves a request before authentication; null means refuse, never fallback.
+
+---
+
+### TenantScope
+
+```ts
+type TenantScope = Readonly<{
+  tenantId: TenantId;
+  origin: string;
+  durableName: string;
+  computerName: string;
+  workspacePrefix: string;
+  repositoryPrefix: string;
+}>;
+```
+
+The only source of durable names for a standalone Oyster tenant.
+
+---
+
+### ResolvedTenant
+
+```ts
+type ResolvedTenant = Readonly<{
+  scope: TenantScope;
+  auth: OysterAuth;
+}>;
+```
+
+A host-selected scope paired with its existing authentication port.
+
+---
+
+### OysterTenancy
+
+```ts
+type OysterTenancy = Readonly<{
+  resolve: Promise<Readonly<{
+    scope: TenantScope;
+    auth: OysterAuth;
+  }> | null>;
+}>;
+```
+
+Resolve an origin-scoped host; null refuses the request without a fallback.
+
+## Variables
+
+### tenantIdSchema
+
+```ts
+const tenantIdSchema: brand<String, "OysterTenantId">;
+```
+
+A host-minted tenant slug: 2–40 lowercase ASCII letters or digits, with single
+interior hyphens. The repository separator `--` is forbidden. Hosts resolve it
+before authentication; App-controlled inputs never select it.
+
+---
+
+### defaultTenant
+
+```ts
+const defaultTenant: TenantId;
+```
+
+The single-tenant Oyster identity whose durable names remain unchanged.
+
+## Functions
+
+### tenantScope()
+
+```ts
+function tenantScope(tenantId, origin): TenantScope;
+```
+
+Name tenant-owned stores without changing any default-tenant name. The `t.`
+repository namespace cannot be a default installation slug, which forbids dots.
+Hub supplies its own Team-scoped ports and does not use this naming contract.
+
+#### Parameters
+
+| Parameter  | Type                                     |
+| ---------- | ---------------------------------------- |
+| `tenantId` | `string` & `Brand`\<`"OysterTenantId"`\> |
+| `origin`   | `string`                                 |
+
+#### Returns
+
+[`TenantScope`](#tenantscope)
+
+---
+
+### singleTenant()
+
+```ts
+function singleTenant(origin): TenantResolver;
+```
+
+Admit defaultTenant only at the configured origin. Scheme, host and port must
+match after URL canonicalization; unknown origins never fall back to default.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `origin`  | `string` |
+
+#### Returns
+
+[`TenantResolver`](#tenantresolver)
+
+---
+
+### implicitTenancy()
+
+```ts
+function implicitTenancy(origin, auth): OysterTenancy;
+```
+
+Preserve the default tenant's names and auth only at the configured origin.
+
+#### Parameters
+
+| Parameter | Type                               |
+| --------- | ---------------------------------- |
+| `origin`  | `string`                           |
+| `auth`    | [`OysterAuth`](host.md#oysterauth) |
+
+#### Returns
+
+[`OysterTenancy`](#oystertenancy)