@zveltio/sdk 3.0.0-beta.76 → 3.0.0-beta.78

package/README.md

@@ -186,18 +186,18 @@ await sync.stop();
 The engine exposes two endpoints for batch sync:
 
 - `POST /api/sync/push` — send offline operations to server
-- `POST /api/sync/pull` — pull changes since a timestamp
+- `POST /api/sync/pull` — pull changes after your cursors
 
 `SyncManager.pull()` uses `/api/sync/pull` and keeps its cursors in the local store. Both endpoints take a
 session only: a client authenticated by an API key gets 403, and `pull()` then falls back to paging the
 collections API, which cannot report deletes.
 
-A pull returns at most 1000 rows per collection. Send `{ collections, since, cursors }`, merge the
+A pull returns at most 1000 rows per collection. Send `{ collections, cursors }`, merge the
 response's `cursors` into yours, and pull again while `hasMore` is true. Keep `cursors` for the next
-sync — a collection's cursor replaces `since` for it, and is the only position that pages through rows
-sharing one `updated_at` (a bulk import).
+sync; a collection without one is read from its start. Cursors are opaque: there is no timestamp
+position, because a timestamp cannot page through rows sharing one `updated_at` (a bulk import).
 
 A row deleted on the server comes back as `{ operation: 'delete', data: null }`; drop your copy. Deletes are
-kept for 30 days: a cursor older than that gets `resync[collection] === true`, and the collection restarts
+kept for 30 days: a cursor last caught up longer ago than that gets `resync[collection] === true`, and the collection restarts
 from the first row — drop your synced copies of it before applying the page. A first pull (no cursor) gets
 no deletes, so start it from an empty copy.

package/dist/ddl/index.d.ts

@@ -84,6 +84,17 @@ export interface CollectionDefinition {
     isSystem?: boolean;
     schemaLocked?: boolean;
 }
+/** A row from `zvd_relations`, as `getRelations` returns it. */
+export interface RelationRecord {
+    id: string;
+    name: string;
+    type: string;
+    source_collection: string;
+    source_field: string;
+    target_collection: string;
+    target_field: string | null;
+    junction_table: string | null;
+}
 /** A row from `zv_collections` / `getCollection` / `getCollections`. The
  *  exact shape is engine-internal; this interface only fixes the fields
  *  extensions are documented to read. Treat unknown keys as best-effort. */
@@ -135,6 +146,8 @@ export interface DDLManager {
     removeField(db: DDLManagerDb, collectionName: string, fieldName: string): Promise<void>;
     /** List every collection registered in `zv_collections`. */
     getCollections(db: DDLManagerDb): Promise<CollectionRecord[]>;
+    /** Every registered relation, or only those whose source or target is `collection`. */
+    getRelations(db: DDLManagerDb, collection?: string): Promise<RelationRecord[]>;
     /** Read a single collection by name. Returns `null` when missing. */
     getCollection(db: DDLManagerDb, name: string): Promise<CollectionRecord | null>;
     /** Update display-only metadata (label, description, icon, sort, etc.). */
@@ -142,6 +155,9 @@ export interface DDLManager {
     /** Introspect the live PG table and return its field configs. Useful for
      *  extensions that auto-discover schema changes. */
     introspectTable(db: DDLManagerDb, collectionName: string): Promise<FieldDefinition[]>;
+    /** Every physical column of the collection's table, system columns included,
+     *  in table order; `[]` when the table does not exist. */
+    columnNames(db: DDLManagerDb, collectionName: string): Promise<string[]>;
     /** Re-read PG and write the result back to `zv_collections.fields`. Returns
      *  the number of changes detected. */
     syncFieldsFromDB(db: DDLManagerDb, collectionName: string): Promise<number>;

package/dist/ddl/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ddl/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ddl/index.ts"],"names":[],"mappings":"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"}

package/dist/extension/capabilities.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Capabilities as TYPES — roadmap R8: "an undeclared capability is a compile
+ * error, not a runtime refusal".
+ *
+ * The engine refuses a gated `ctx.internals` member whose capability the
+ * manifest does not declare (`CapabilityDeniedError`). That refusal happens the
+ * first time the code path runs — often in production, on the request that
+ * needed it. Declaring the capabilities to TypeScript as well moves the same
+ * answer to the editor:
+ *
+ *   export default defineExtension(['ddl', 'secrets'], {
+ *     name: 'my-ext',
+ *     category: 'tools',
+ *     async register(app, ctx) {
+ *       await ctx.internals.encryptSecret('x');      // ok: 'secrets'
+ *       await ctx.internals.deleteUser(db, 'u');      // compile error: needs 'auth:users'
+ *     },
+ *   });
+ *
+ * The list passed to `defineExtension` is a statement to the compiler; the
+ * manifest's `permissions` remains what the engine enforces and what an
+ * administrator approves. `zveltio extension validate` compares the two.
+ *
+ * These two tables mirror the engine's `CAPABILITIES` and `INTERNALS_CAPABILITY`
+ * (`packages/engine/src/lib/extensions/capabilities.ts`); the engine's unit test
+ * `sdk-capability-types.test.ts` fails when they drift apart.
+ */
+/** Every capability an extension may declare, `net:<host>` aside. */
+export declare const EXTENSION_CAPABILITIES: readonly ["db:admin", "tenant:enter", "ddl", "secrets", "auth:session", "auth:users", "identity:provision", "audit:read", "data:write", "data:system", "notifications", "files", "documents", "edge-functions", "introspection", "storage", "cron", "field-types"];
+/** A capability name, including the parameterised `net:<host>`. */
+export type Capability = (typeof EXTENSION_CAPABILITIES)[number] | `net:${string}`;
+/** The `ctx.internals` members a capability unlocks. */
+export declare const CAPABILITY_MEMBERS: {
+    readonly enqueueDDLJob: "ddl";
+    readonly introspectSchema: "introspection";
+    readonly extensionRegistry: "introspection";
+    readonly encryptSecret: "secrets";
+    readonly decryptSecret: "secrets";
+    readonly deriveTokenHash: "secrets";
+    readonly createBetterAuthSession: "auth:session";
+    readonly deleteUser: "auth:users";
+    readonly exportUserData: "auth:users";
+    readonly revokeUserSessions: "auth:users";
+    readonly setUserActive: "auth:users";
+    readonly liftOwnBan: "auth:users";
+    readonly provisionUser: "identity:provision";
+    readonly listTenantUsers: "identity:provision";
+    readonly updateUserProfile: "identity:provision";
+    readonly addTenantMember: "identity:provision";
+    readonly removeTenantMember: "identity:provision";
+    readonly setTenantMembershipEnd: "identity:provision";
+    readonly readAuditActivity: "audit:read";
+    readonly createRecord: "data:write";
+    readonly updateRecord: "data:write";
+    readonly deleteRecord: "data:write";
+    readonly asSystem: "data:system";
+    readonly sendNotification: "notifications";
+    readonly moveToTrash: "files";
+    readonly generatePDFAsync: "documents";
+    readonly runEdgeFunction: "edge-functions";
+};
+/** Members of `ctx.internals` that need a capability. */
+export type GatedMember = keyof typeof CAPABILITY_MEMBERS;
+/** The gated members the capabilities `C` unlock. */
+export type MembersUnlockedBy<C extends string> = {
+    [K in GatedMember]: (typeof CAPABILITY_MEMBERS)[K] extends C ? K : never;
+}[GatedMember];
+/** The gated members `C` does NOT unlock — removed from the narrowed type. */
+export type MembersLockedFor<C extends string> = Exclude<GatedMember, MembersUnlockedBy<C>>;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/extension/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/extension/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,oQAmBzB,CAAC;AAEX,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,MAAM,EAAE,CAAC;AAEnF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4B6C,CAAC;AAE7E,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAE1D,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,IAAI;KAC/C,CAAC,IAAI,WAAW,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK;CACzE,CAAC,WAAW,CAAC,CAAC;AAEf,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/extension/capabilities.js

@@ -0,0 +1,78 @@
+/**
+ * Capabilities as TYPES — roadmap R8: "an undeclared capability is a compile
+ * error, not a runtime refusal".
+ *
+ * The engine refuses a gated `ctx.internals` member whose capability the
+ * manifest does not declare (`CapabilityDeniedError`). That refusal happens the
+ * first time the code path runs — often in production, on the request that
+ * needed it. Declaring the capabilities to TypeScript as well moves the same
+ * answer to the editor:
+ *
+ *   export default defineExtension(['ddl', 'secrets'], {
+ *     name: 'my-ext',
+ *     category: 'tools',
+ *     async register(app, ctx) {
+ *       await ctx.internals.encryptSecret('x');      // ok: 'secrets'
+ *       await ctx.internals.deleteUser(db, 'u');      // compile error: needs 'auth:users'
+ *     },
+ *   });
+ *
+ * The list passed to `defineExtension` is a statement to the compiler; the
+ * manifest's `permissions` remains what the engine enforces and what an
+ * administrator approves. `zveltio extension validate` compares the two.
+ *
+ * These two tables mirror the engine's `CAPABILITIES` and `INTERNALS_CAPABILITY`
+ * (`packages/engine/src/lib/extensions/capabilities.ts`); the engine's unit test
+ * `sdk-capability-types.test.ts` fails when they drift apart.
+ */
+/** Every capability an extension may declare, `net:<host>` aside. */
+export const EXTENSION_CAPABILITIES = [
+    'db:admin',
+    'tenant:enter',
+    'ddl',
+    'secrets',
+    'auth:session',
+    'auth:users',
+    'identity:provision',
+    'audit:read',
+    'data:write',
+    'data:system',
+    'notifications',
+    'files',
+    'documents',
+    'edge-functions',
+    'introspection',
+    'storage',
+    'cron',
+    'field-types',
+];
+/** The `ctx.internals` members a capability unlocks. */
+export const CAPABILITY_MEMBERS = {
+    enqueueDDLJob: 'ddl',
+    introspectSchema: 'introspection',
+    extensionRegistry: 'introspection',
+    encryptSecret: 'secrets',
+    decryptSecret: 'secrets',
+    deriveTokenHash: 'secrets',
+    createBetterAuthSession: 'auth:session',
+    deleteUser: 'auth:users',
+    exportUserData: 'auth:users',
+    revokeUserSessions: 'auth:users',
+    setUserActive: 'auth:users',
+    liftOwnBan: 'auth:users',
+    provisionUser: 'identity:provision',
+    listTenantUsers: 'identity:provision',
+    updateUserProfile: 'identity:provision',
+    addTenantMember: 'identity:provision',
+    removeTenantMember: 'identity:provision',
+    setTenantMembershipEnd: 'identity:provision',
+    readAuditActivity: 'audit:read',
+    createRecord: 'data:write',
+    updateRecord: 'data:write',
+    deleteRecord: 'data:write',
+    asSystem: 'data:system',
+    sendNotification: 'notifications',
+    moveToTrash: 'files',
+    generatePDFAsync: 'documents',
+    runEdgeFunction: 'edge-functions',
+};

package/dist/extension/index.d.ts

@@ -1,3 +1,4 @@
+import type { Capability, MembersLockedFor } from './capabilities.js';
 import type { Context, Hono } from 'hono';
 import type { Kysely, RawBuilder } from 'kysely';
 export { permissionGate } from './permission-gate.js';
@@ -164,7 +165,14 @@ export interface ExtensionConfig {
  * Default `any` keeps legacy extensions compiling untouched. Migrated
  * extensions get full Kysely autocomplete + typo detection.
  */
-export interface ExtensionContext<DB = any> {
+/**
+ * `C` — the capabilities this extension declared, when it says so through
+ * `defineExtension`. It narrows `internals` to the members those capabilities
+ * unlock and `adminDb` to `db:admin`, so an undeclared capability is a compile
+ * error rather than a `CapabilityDeniedError` on the first request that needs
+ * it. Defaults to every capability: code that does not opt in keeps today's type.
+ */
+export interface ExtensionContext<DB = any, C extends string = Capability> {
     /**
      * Kysely database instance (restricted — cannot query zv_* system tables).
      * Typed via the `DB` generic; use `ZveltioExtension<MySchema>` to opt in.
@@ -190,7 +198,7 @@ export interface ExtensionContext<DB = any> {
      * Use for legitimately global operations (platform-wide reporting, backup).
      * Declaring `db:admin` surfaces the cross-tenant access at review + install.
      */
-    adminDb?: Kysely<DB>;
+    adminDb?: 'db:admin' extends C ? Kysely<DB> : never;
     /**
      * Per-request, tenant-scoped database. Returns the request's tenant
      * transaction (so the `zveltio.current_tenant` GUC is set and FORCE-RLS rows
@@ -307,7 +315,7 @@ export interface ExtensionContext<DB = any> {
      * Engine-internal helpers. Stable across patch versions but may break across
      * minor versions. First-party extensions only.
      */
-    internals: ExtensionInternals<DB>;
+    internals: Omit<ExtensionInternals<DB>, MembersLockedFor<C>>;
 }
 /**
  * Engine-internal helpers passed via `ctx.internals.*`.
@@ -383,6 +391,12 @@ export interface ExtensionInternals<DB = unknown> {
      * like a request's: the tenant GUC is set and `SET LOCAL ROLE` applied, so
      * the isolation policies bind.
      *
+     * Only the tenant the work already runs as — the request's, or the job's —
+     * is entered without a capability. Another tenant, or any tenant where none
+     * runs (load time, a timer), needs `tenant:enter` (or `db:admin`, which
+     * implies it); without it the promise rejects.
+     * A fire-and-forget job started from a handler keeps the handler's tenant.
+     *
      *     await ctx.internals.withTenantIsolation(tenantId, async (db) => {
      *       await db.selectFrom('zvd_things').selectAll().execute();
      *     });
@@ -475,7 +489,12 @@ export interface ExtensionInternals<DB = unknown> {
         hidden: Set<string>;
         readOnly: Set<string>;
     }>;
-    /** The Casbin role behind a user — what `getColumnAccess` keys on. */
+    /**
+     * The single role behind a user — what `getColumnAccess` keys on. Drawn from
+     * Casbin, the one source of roles: `god` (the instance attribute) > `member`
+     * (the `g <user> member *` row every account gets) > `public`. A user's full
+     * role set is `getUserRoles`.
+     */
     resolveUserRole: (user: {
         id?: string;
         role?: string;
@@ -542,6 +561,71 @@ export interface ExtensionInternals<DB = unknown> {
      */
     getUserNames: (userIds: string[]) => Promise<Record<string, string>>;
     isTenantAdmin: (userId: string) => Promise<boolean>;
+    /**
+     * Facts about the tenant this work runs as, scoped by the engine — the path
+     * in place of raw SQL on `"user"`, `zv_tenant_users`, `zv_tenants`,
+     * `pg_class`, `zvd_permissions` and `zv_settings`, which `ctx.db` refuses.
+     */
+    /** People with a membership in force in the running tenant, and its owners/admins. */
+    countMembers: () => Promise<{
+        total: number;
+        admins: number;
+    }>;
+    /** Collection count, and a planner row estimate (`null` on a multi-tenant instance). */
+    getDataStats: () => Promise<{
+        collections: number;
+        records_estimate: number | null;
+    }>;
+    /** Role names granted in the running tenant or in every tenant. */
+    listRoles: () => Promise<string[]>;
+    /** A setting the instance marks public (`is_public`); `null` otherwise. */
+    getPublicSetting: (key: string) => Promise<unknown>;
+    /** Append to the audit log, as a row of the running tenant (instance-level where none runs). The engine stamps `metadata.extension` with the caller. */
+    audit: (event: {
+        type: string;
+        userId?: string;
+        resourceId?: string;
+        resourceType?: string;
+        metadata?: Record<string, unknown>;
+        ip?: string;
+    }) => Promise<void>;
+    /**
+     * Run `fn` acting as the system inside the running tenant, for the named
+     * collections (`['products']`, not `zvd_products`): collection permissions
+     * stand down for `ctx.db` during the call; tenant isolation and the table
+     * guard do not. Needs the `data:system` capability. Every call is audited
+     * with the extension, the user, the collections and `reason`.
+     */
+    asSystem: <T>(collections: readonly string[], fn: () => Promise<T>, opts?: {
+        reason?: string;
+    }) => Promise<T>;
+    /**
+     * The running tenant's recent audit rows, newest first — never another
+     * tenant's, never instance-level events. `limit` defaults to 20, capped at
+     * 100. No `metadata` or `ip`. Needs the `audit:read` capability.
+     */
+    readAuditActivity: (query?: {
+        limit?: number;
+        eventType?: string;
+        resourceType?: string;
+        since?: Date | string;
+    }) => Promise<{
+        id: string;
+        event_type: string;
+        user_id: string | null;
+        resource_type: string | null;
+        resource_id: string | null;
+        created_at: Date;
+    }[]>;
+    /**
+     * How many of the running tenant's audit rows match, from `since` on. Same
+     * scope as `readAuditActivity`; a number, so ungated.
+     */
+    countAuditActivity: (query: {
+        since: Date | string;
+        eventType?: string;
+        resourceType?: string;
+    }) => Promise<number>;
     /**
      * Instance-level admin, as distinct from admin-within-a-tenant.
      *
@@ -558,7 +642,10 @@ export interface ExtensionInternals<DB = unknown> {
     extensionRegistry: any;
     /** Queue an HTML→PDF render via the worker pool. */
     generatePDFAsync: (html: string, options?: Record<string, unknown>) => Promise<unknown>;
-    /** Move a file to the trash bucket (soft delete with TTL). */
+    /**
+     * Move a file to the trash bucket (soft delete with TTL): `(db, fileId, deletedBy)`.
+     * Only a file of the tenant the request or job runs as; outside one it rejects.
+     */
     moveToTrash: (...args: any[]) => Promise<unknown>;
     /** Enqueue an asynchronous DDL job (Ghost Tables, large alters). */
     enqueueDDLJob: (...args: any[]) => Promise<unknown>;
@@ -681,6 +768,47 @@ export interface ExtensionInternals<DB = unknown> {
      * cannot reach either. Needs the `auth:users` capability.
      */
     revokeUserSessions: (userId: string) => Promise<void>;
+    /**
+     * What the engine's own tables hold about a user — profile, their audit
+     * rows in every tenant and at instance level, notifications, the API keys
+     * they created (names, never secrets) and their approval requests — for a
+     * data-subject access request. `null` when there is no such user. Needs the
+     * `auth:users` capability.
+     */
+    exportUserData: (userId: string) => Promise<{
+        profile: {
+            id: string;
+            name: string | null;
+            email: string;
+            created_at: string;
+        } | null;
+        audit_log: Array<{
+            action: string;
+            collection: string | null;
+            record_id: string | null;
+            created_at: string;
+        }>;
+        notifications: Array<{
+            title: string;
+            message: string | null;
+            type: string | null;
+            is_read: boolean;
+            created_at: string;
+        }>;
+        api_keys: Array<{
+            name: string;
+            key_prefix: string | null;
+            scopes: unknown;
+            created_at: string;
+        }>;
+        approval_requests: Array<{
+            id: string;
+            collection: string;
+            record_id: string | null;
+            status: string;
+            requested_at: string;
+        }>;
+    } | null>;
     /**
      * `false` stops the user signing in by ANY method (password, magic link,
      * passkey, OAuth, SSO) and revokes their sessions; `true` lets them back in
@@ -702,6 +830,100 @@ export interface ExtensionInternals<DB = unknown> {
      * `auth:users` capability.
      */
     liftOwnBan: (db: unknown, userId: string) => Promise<boolean>;
+    /** Whether at most one tenant exists — then every user belongs to it. Ungated. */
+    isSingleTenantInstance: () => Promise<boolean>;
+    /**
+     * The account for `email` (case-insensitive), created when there is none:
+     * verified, no password, never god, in no tenant. Works while
+     * self-registration is off. Inside `withTenantIsolation` it is created in
+     * that transaction, and a rollback takes it back. An account that already
+     * exists comes back only if the running tenant has a claim to it: a member
+     * here with no power elsewhere beyond plain membership, any account but god
+     * and the instance admins on a single-tenant instance, or a bare record (no
+     * credential, membership or grant). Anyone else is `account_exists`: they join
+     * through an invitation, which proves they control the address.
+     */
+    provisionUser: (input: {
+        email: string;
+        name?: string;
+    }) => Promise<{
+        user: ProvisionedUser;
+        created: boolean;
+    }>;
+    /**
+     * Users of the running tenant — a membership there, lapsed included — or
+     * every user on a single-tenant instance (`membership: null`). By creation
+     * order; `limit` defaults to 100, at most 1000.
+     */
+    listTenantUsers: (db: unknown, query?: {
+        email?: string;
+        userId?: string;
+        limit?: number;
+        offset?: number;
+    }) => Promise<Array<ProvisionedUser & {
+        membership: TenantMembershipInfo | null;
+    }>>;
+    /**
+     * Rename or re-address a user the running tenant ALONE holds: a membership
+     * here (any user on a single-tenant instance), not god, not an instance admin,
+     * no membership or grant in any other tenant (`user_not_owned` otherwise).
+     * `db` is your transaction.
+     */
+    updateUserProfile: (db: unknown, userId: string, patch: {
+        name?: string;
+        email?: string;
+    }) => Promise<ProvisionedUser>;
+    /**
+     * Make the user a `member` (default) or `viewer` of the running tenant, or
+     * switch between the two, with the matching tenant role. Dates are kept: a
+     * membership that ended is not reopened. An `owner`/`admin` is refused.
+     */
+    addTenantMember: (db: unknown, userId: string, role?: 'member' | 'viewer') => Promise<'added' | 'role_changed' | 'unchanged'>;
+    /**
+     * Remove the user from the running tenant with every role they hold in it.
+     * `orphaned`: no tenant and nothing else holds the account now — deleting it
+     * (`deleteUser`, `auth:users`) is your call. `inForceAnywhere`: a membership
+     * in force remains in some tenant. An owner or admin of the tenant (in the
+     * default tenant, an instance admin) is refused, `role_not_allowed`.
+     */
+    removeTenantMember: (db: unknown, userId: string) => Promise<{
+        removed: boolean;
+        orphaned: boolean;
+        inForceAnywhere: boolean;
+    }>;
+    /**
+     * Set when the user's membership of the running tenant ends: `'now'`, an
+     * ISO-8601 instant, or `null` (open-ended). `ifInForce` changes only a
+     * membership in force; `ifValidTo` only one whose end is still exactly that
+     * value. `null` when the user is no member here. An owner or admin is
+     * refused, `role_not_allowed`.
+     */
+    setTenantMembershipEnd: (db: unknown, userId: string, validTo: string | null, guard?: {
+        ifInForce?: boolean;
+        ifValidTo?: string | null;
+    }) => Promise<{
+        changed: boolean;
+        previousValidTo: string | null;
+        validTo: string | null;
+        inForceAnywhere: boolean;
+    } | null>;
+}
+/** A user as `ctx.internals` identity provisioning returns it. */
+export interface ProvisionedUser {
+    id: string;
+    email: string;
+    name: string;
+    emailVerified: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A user's membership of the running tenant. */
+export interface TenantMembershipInfo {
+    role: 'owner' | 'admin' | 'member' | 'viewer';
+    validFrom: string;
+    /** `null`: open-ended. */
+    validTo: string | null;
+    inForce: boolean;
 }
 /**
  * Entity-access scope handed to each extension via `ctx.entityAccess`.
@@ -776,18 +998,32 @@ export interface QueryAlterScope {
  * `register()` is idempotent within a scope (replaces on duplicate), so an
  * extension's `register()` can safely run multiple times during hot-reload.
  */
+/**
+ * A manifest `dependencies` / `optionalDependencies` entry. A required one must be
+ * installed for this extension to load; an optional one need not be — its
+ * services then read as `null`. Either way, the extensions named in these two
+ * lists are the only ones whose services `ctx.services` hands this one.
+ */
+export interface ManifestDependency {
+    name: string;
+    minVersion?: string;
+}
 export interface ServiceRegistry {
     /**
-     * Publish a service under a name.
+     * Publish a service under a name, which must be `<this extension's name>.<x>`.
      * Idempotent: re-registering the same name from the same extension replaces.
      * Throws if a different extension already owns that name.
      */
     register<T = unknown>(name: string, value: T): void;
     /** Remove a service this extension previously registered. No-op if not owned. */
     unregister(name: string): void;
-    /** Get a service. Returns `null` if not registered. */
+    /**
+     * Get a service. Returns `null` if not registered (an optional dependency
+     * that is not installed). Throws if its owner is not this extension or one in
+     * its manifest `dependencies` / `optionalDependencies`.
+     */
     get<T = unknown>(name: string): T | null;
-    /** Check if a service is registered. */
+    /** Check if a service is registered. Throws as `get` does for an undeclared owner. */
     has(name: string): boolean;
     /**
      * Wait for a service to be registered. Resolves immediately if already there.
@@ -912,7 +1148,7 @@ export type MountStrategy = 'global' | 'subapp';
  *     }
  *   };
  */
-export interface ZveltioExtension<DB = any> {
+export interface ZveltioExtension<DB = any, C extends string = Capability> {
     /** Unique name — must match manifest.json `name` exactly (e.g. `'hr/employees'`). */
     name: string;
     /** Category shown in the marketplace (e.g. `'hr'`, `'finance'`, `'content'`). */
@@ -927,7 +1163,7 @@ export interface ZveltioExtension<DB = any> {
      * Called once when the extension is activated.
      * Register Hono routes, subscribe to events, etc.
      */
-    register: (app: Hono, ctx: ExtensionContext<DB>) => Promise<void>;
+    register: (app: Hono, ctx: ExtensionContext<DB, C>) => Promise<void>;
     /** Register custom Studio field types contributed by this extension. */
     registerFieldTypes?: (registry: FieldTypeRegistryAPI) => void;
     /** Return absolute paths to SQL migration files, run in order on first activation. */
@@ -1057,5 +1293,21 @@ export interface AssetPreviewHandler {
     }) => boolean;
     component: any;
 }
+/**
+ * Declare an extension together with the capabilities it uses, so `ctx` is typed
+ * by them (roadmap R8). The list must match `permissions` in manifest.json —
+ * the manifest is what the engine enforces and an administrator approves;
+ * `zveltio extension validate` reports a difference.
+ *
+ *   export default defineExtension(['secrets'], { name, category, register });
+ *
+ * Returns the extension unchanged, with the list attached as `capabilities`.
+ */
+/** `ZveltioExtension`'s own default schema type, without spelling it again. */
+type DefaultExtensionDB = ZveltioExtension extends ZveltioExtension<infer D> ? D : never;
+export declare function defineExtension<const C extends readonly Capability[], DB = DefaultExtensionDB>(capabilities: C, extension: ZveltioExtension<DB, C[number]>): ZveltioExtension<DB, C[number]> & {
+    readonly capabilities: C;
+};
 export type { Hono };
+export * from './capabilities.js';
 //# sourceMappingURL=index.d.ts.map