@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/principals.d.ts

@@ -0,0 +1,302 @@
+import { Effect, Schema } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { type SqlError } from "effect/unstable/sql/SqlError";
+import { type ResolvedFeedback } from "../feedback-config.js";
+import { type ScopeManifest, type WorkflowManifest } from "../manifest.js";
+import { type Ontology } from "../ontology.js";
+import type { Principal, StoredRecord } from "../runtime.js";
+import type { SignInCheck } from "../sign-in.js";
+import { MemberNotFound, PrincipalRejected, UnknownRole } from "./errors.js";
+import { type WorkloadExecution } from "./workload.js";
+export { WORKFLOW_USER_PROVIDER, workflowSubject } from "./workflow-users.js";
+export { revokeMemberSessions } from "./member-tables.js";
+/** API keys are `ssk_<key id>.<secret>`. */
+export declare const API_KEY_PREFIX = "ssk_";
+/**
+ * PBKDF2-SHA256 iterations for a key's secret: about 5 ms per verification on Node. The secret
+ * already carries 256 bits of entropy, so the KDF is not what protects it; it exists so that stored
+ * secrets are handled like any password storage, and it must stay cheap because it runs on every
+ * request authenticated with an API key.
+ */
+export declare const API_KEY_ITERATIONS = 10000;
+export interface ApiKeyParts {
+    /** Stored in clear, to find the key's row. */
+    readonly keyId: string;
+    /** Stored only as a salted hash. */
+    readonly secret: string;
+}
+/** A new API key: 8 random bytes of key id and 32 of secret. Show it once; it is not stored. */
+export declare function generateApiKey(): string;
+/** The key id and secret of a key, or `undefined` when it is not one. */
+export declare function parseApiKey(key: string): ApiKeyParts | undefined;
+/** PBKDF2-SHA256 of a secret with its salt, in hex: what `_api_keys.hash` holds. */
+export declare function hashApiKeySecret(secret: string, salt: string): Promise<string>;
+/** The claims of a verified sign-in token that identify and describe a member. */
+export interface IdentityClaims {
+    /** Who signed the member in, for example `neon-auth`. */
+    readonly identityProvider: string;
+    /** The token's subject. */
+    readonly identitySubject: string;
+    /** Verified by the trusted issuer; never an unverified address from a sign-in form. */
+    readonly email?: string;
+    readonly name?: string;
+}
+/**
+ * Every request authenticates, so recording each one would write a history row per request. A
+ * returning member's sign-in is recorded once the last one is older than a Neon Auth token's
+ * lifetime: about once per token, which is how often an active member authenticates afresh.
+ */
+export declare const SIGN_IN_RECORD_INTERVAL_MS: number;
+/** User rows as principal resolution reads them. */
+declare const UserRow: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["member", "service"]>;
+    readonly active: Schema.Boolean;
+}>;
+type UserRow = typeof UserRow.Type;
+/** The history actions of member role changes, as the generated `user` actions name them. */
+export declare const MEMBER_HISTORY_ACTIONS: {
+    readonly invite: "user.invite";
+    readonly grantRoles: "user.grant_roles";
+    readonly revokeRoles: "user.revoke_roles";
+    readonly deactivate: "user.deactivate";
+    readonly reactivate: "user.reactivate";
+};
+/** The SQL projection also used by transactional storage permission rechecks. */
+export interface PrincipalRolesSql {
+    readonly unsafe: (text: string, args: ReadonlyArray<unknown>) => Effect.Effect<ReadonlyArray<Readonly<Record<string, unknown>>>, SqlError>;
+}
+export declare function rolesOf(ontology: Ontology, sql: PrincipalRolesSql, user: UserRow): Effect.Effect<Principal, SqlError>;
+/** Resolve a workspace-owned identity/session by user id, with current activity and roles. */
+export declare function resolvePrincipalById(ontology: Ontology, sql: SqlClient.SqlClient, id: string): Effect.Effect<Principal, SqlError | PrincipalRejected, never>;
+/**
+ * The principal of a member signed in with a verified token. On first sign-in the member's `user`
+ * is linked by email when someone invited them; a person nobody invited is rejected as
+ * `not_invited` under the `invited` policy and becomes a member holding only `member` under
+ * `open`. Every sign-in that lets the member in sets `lastSignInAt`, at most once per
+ * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. If the User row is busy, recording is
+ * deferred to a later request instead of delaying authentication. Inactive users are rejected.
+ */
+export declare function resolvePrincipalByIdentity(ontology: Ontology, claims: IdentityClaims): Effect.Effect<Principal, PrincipalRejected, SqlClient.SqlClient>;
+/** Resolve the workspace's stable keyless pipeline service, without customer roles or sign-in. */
+export declare function resolvePipelineWorker(ontology: Ontology, execution: WorkloadExecution): Effect.Effect<Principal, PrincipalRejected, SqlClient.SqlClient>;
+/** A keyless hook actor with only the workspace's opted-in role; deactivated actors stay inactive. */
+export declare function resolveHookService(ontology: Ontology, heldRole: string): Effect.Effect<Principal, PrincipalRejected, SqlClient.SqlClient>;
+/**
+ * A workflow user's permissions: what `member` and the workflow's role grant, as `check` verified.
+ * A `*:*` of member's is spelled out per entity, so that it covers what a named grant covers and
+ * never the pipeline worker's workload wildcard; `check` refuses a workflow role holding `*:*`. An
+ * entity a wildcard covers only some verbs of, the user, is spelled out with those verbs.
+ */
+export declare function workflowPermissions(ontology: Ontology, role: string): ReadonlyArray<string>;
+/**
+ * Resolve the keyless service user a workflow's runs act as: one per declared workflow, holding
+ * exactly the workflow's role, named by `workflows:<workspace id>:<workflow name>`. Deploy creates
+ * it; a run before that creates it here. It never rewrites roles: a user whose roles are not
+ * exactly the declared role is rejected (`role_mismatch`) until a deploy reconciles it. A workflow
+ * the serving ontology does not declare is rejected, as is an inactive user. Its permissions are
+ * what `member` and its role grant, and every action checks them as for any caller.
+ */
+export declare function resolveWorkflowUser(ontology: Ontology, input: {
+    readonly workspaceId: string;
+    readonly workflow: string;
+}): Effect.Effect<Principal, PrincipalRejected, SqlClient.SqlClient>;
+/**
+ * Brings the workflow users of the workspace in line with the ontology's workflows, as deploy does
+ * in the migration's transaction: each declared workflow's user is created if missing, reactivated
+ * and given exactly the workflow's role; a user whose workflow is no longer declared is
+ * deactivated, so its runs are refused and history keeps its name. Repeating it changes nothing.
+ * Database failures, including those of the history writes, fail with their `SqlError`.
+ */
+export declare function reconcileWorkflowUsers(ontology: Ontology, input: {
+    readonly workspaceId: string;
+}): Effect.Effect<void, SqlError, SqlClient.SqlClient>;
+/**
+ * The principal of an API key, with the permissions its roles have in the ontology. Unknown and
+ * revoked keys and inactive users are rejected.
+ */
+export declare function resolvePrincipalByApiKey(ontology: Ontology, key: string): Effect.Effect<Principal, PrincipalRejected, SqlClient.SqlClient>;
+/**
+ * A member by user id, with the roles they hold now: whom an OAuth grant acts for. `undefined` for
+ * an unknown user, a service and an inactive member.
+ */
+export declare function resolveMemberById(ontology: Ontology, userId: string): Effect.Effect<Principal | undefined, never, SqlClient.SqlClient>;
+export interface CreatedApiKey {
+    readonly id: string;
+    /** The key itself. It is not stored and cannot be shown again. */
+    readonly key: string;
+}
+/** Issues an API key for a user. */
+export declare function createApiKey(input: {
+    readonly userId: string;
+    readonly label: string;
+}): Effect.Effect<CreatedApiKey, never, SqlClient.SqlClient>;
+/** Revokes an API key. Revoking it again changes nothing. */
+export declare function revokeApiKey(input: {
+    readonly id: string;
+}): Effect.Effect<void, never, SqlClient.SqlClient>;
+/** Replaces the roles a user was given. Members hold `member` whatever is assigned. */
+export declare function setUserRoles(ontology: Ontology, input: {
+    readonly userId: string;
+    readonly roles: ReadonlyArray<string>;
+}): Effect.Effect<void, UnknownRole, SqlClient.SqlClient>;
+/**
+ * Creates a service user with roles and a first API key, as the app or the CLI does for the
+ * website's intake key.
+ */
+export declare function createServiceUser(ontology: Ontology, input: {
+    readonly name: string;
+    readonly roles: ReadonlyArray<string>;
+    readonly keyLabel: string;
+}): Effect.Effect<{
+    readonly user: StoredRecord;
+    readonly apiKey: CreatedApiKey;
+}, UnknownRole, SqlClient.SqlClient>;
+/** The roles and the built-in user of a deployed ontology, as its manifest lists them. */
+export interface PrincipalsManifest {
+    readonly feedback?: ResolvedFeedback;
+    readonly roles: ReadonlyArray<{
+        readonly name: string;
+        readonly description: string;
+        readonly builtIn: boolean;
+        /** Absent from version 1 manifests: such a role grants nothing here. */
+        readonly permissions?: ReadonlyArray<string> | undefined;
+        /** Since version 10, the scoped ones with their `where`. Absent reads as none. */
+        readonly scopes?: ReadonlyArray<ScopeManifest> | undefined;
+    }>;
+    /**
+     * The deployed entities, of which only the built-in user's property names are read. Without them,
+     * the deployed user is taken to have every property of this SDK's `User`.
+     */
+    readonly entities?: ReadonlyArray<{
+        readonly builtIn: boolean;
+        readonly properties: ReadonlyArray<{
+            readonly name: string;
+        }>;
+    }>;
+    /** The deployed workflows, whose users this ontology resolves and reconciles. Absent reads as none. */
+    readonly workflows?: ReadonlyArray<WorkflowManifest> | undefined;
+}
+/**
+ * An ontology with only the built-in `User` and the manifest's roles, with their permissions: what
+ * managing principals needs. The platform holds a deployed ontology's manifest, not its code, and
+ * users, roles and API keys live in tables the ontology's own entities do not shape. The roles'
+ * permissions name entities this ontology does not have; they were checked when the manifest was
+ * built, so they are not checked again, and neither are its workflows, which it carries for their
+ * users. The user keeps only the properties the deployed table has.
+ */
+export declare function principalsOntology(manifest: PrincipalsManifest): Ontology;
+/** An API key as the platform lists it: everything but the secret. */
+export interface ApiKeySummary {
+    readonly id: string;
+    readonly keyId: string;
+    readonly label: string;
+    readonly createdAt: string;
+    readonly revokedAt: string | undefined;
+    readonly user: {
+        readonly id: string;
+        readonly name: string;
+        readonly active: boolean;
+    };
+    readonly roles: ReadonlyArray<string>;
+}
+/** Every API key, oldest first, revoked ones included. */
+export declare function listApiKeys(): Effect.Effect<ReadonlyArray<ApiKeySummary>, never, SqlClient.SqlClient>;
+/** One API key by its id, or undefined. */
+export declare function findApiKey(input: {
+    readonly id: string;
+}): Effect.Effect<ApiKeySummary | undefined, never, SqlClient.SqlClient>;
+/** Where a member stands: invited and not signed in yet, signed in, or deactivated. */
+export type MemberStatus = "invited" | "active" | "inactive";
+/** A member as the platform lists it: a person's `user`, with the roles assigned to it. */
+export interface MemberSummary {
+    readonly id: string;
+    /** Members created at sign-in without a usable email have none. */
+    readonly email: string | undefined;
+    readonly name: string;
+    readonly active: boolean;
+    readonly blocked?: true;
+    readonly identities?: ReadonlyArray<{
+        readonly provider: string;
+        readonly subject: string;
+        readonly username?: string;
+    }>;
+    /** `invited` until the member first signs in, `inactive` once deactivated. */
+    readonly status: MemberStatus;
+    /** The roles assigned to the member, sorted. `member` is implicit and not listed. */
+    readonly roles: ReadonlyArray<string>;
+    /** When the member last signed in, ISO 8601 in UTC; none before their first sign-in. */
+    readonly lastSignInAt: string | undefined;
+}
+/** A member by user id, or by the email they sign in with, in any case. */
+export type MemberKey = {
+    readonly id: string;
+} | {
+    readonly email: string;
+};
+/** Every member, signed in or not, by email. */
+export declare function listMembers(): Effect.Effect<ReadonlyArray<MemberSummary>, never, SqlClient.SqlClient>;
+/**
+ * Whether a person may sign in with this address, and how; it reads and changes nothing else.
+ * Under `invited`, an active member who signed in with Neon Auth before gets `code`, an active
+ * member who has not gets `link`, and anyone else is not allowed: a deactivated member is answered
+ * like an unknown address. Under `open`, unblocked addresses get `link`.
+ */
+export declare function checkSignIn(ontology: Ontology, email: string): Effect.Effect<SignInCheck, never, SqlClient.SqlClient>;
+/** A change to one member's roles, by id or email. Only an email can invite a new member. */
+export type MemberRolesChange = MemberKey & {
+    /** The name of a member this change creates; defaults to the email. */
+    readonly name?: string | undefined;
+    /**
+     * Roles to add. When no user has the email, a change with `grant` creates the member, even with
+     * no roles (they then hold only `member`); a change without it fails with MemberNotFound.
+     */
+    readonly grant?: ReadonlyArray<string> | undefined;
+    /** Roles to remove, or every assigned role. A role also in `grant` stays assigned. */
+    readonly revoke?: ReadonlyArray<string> | "all" | undefined;
+};
+/**
+ * Adds and removes a member's roles in one transaction. Creates a member only for an unknown email
+ * when `grant` is given. Granting a role the member holds, or revoking one they do not, changes
+ * nothing. A member created here is linked to their identity by email on first sign-in. The writes
+ * are the `user` actions' own, as platform writes: history names `user.invite`,
+ * `user.revoke_roles` and `user.grant_roles`, without a principal.
+ */
+export declare function updateMemberRoles(ontology: Ontology, change: MemberRolesChange): Effect.Effect<MemberSummary, UnknownRole | MemberNotFound, SqlClient.SqlClient>;
+/**
+ * Grants roles of the ontology to the member with this email, creating the member when no user has
+ * it; their name defaults to the email. Granting a role they hold changes nothing.
+ */
+export declare function grantMemberRoles(ontology: Ontology, input: {
+    readonly email: string;
+    readonly name?: string | undefined;
+    readonly roles: ReadonlyArray<string>;
+}): Effect.Effect<MemberSummary, UnknownRole | MemberNotFound, SqlClient.SqlClient>;
+/**
+ * Removes roles from the member with this email, or every assigned role. The member stays, so
+ * history keeps their name. Roles the ontology no longer declares can be removed too.
+ */
+export declare function revokeMemberRoles(ontology: Ontology, input: {
+    readonly email: string;
+    readonly roles: ReadonlyArray<string> | "all";
+}): Effect.Effect<MemberSummary, UnknownRole | MemberNotFound, SqlClient.SqlClient>;
+/**
+ * Deactivates or reactivates a member, as `user.deactivate` and `user.reactivate` do, as a platform
+ * write. An inactive member keeps their roles and history, and the service rejects their requests.
+ * Deactivation also revokes sessions, including repeated requests.
+ */
+export declare function setMemberActive(ontology: Ontology, input: MemberKey & {
+    readonly active: boolean;
+}): Effect.Effect<MemberSummary, MemberNotFound, SqlClient.SqlClient>;
+export declare function isMemberBlocked(sql: SqlClient.SqlClient, userId: string): Effect.Effect<boolean, SqlError, never>;
+/** Must run in the issuance transaction; the shared User lock serializes insertion with revocation. */
+export declare function lockSessionMember(sql: SqlClient.SqlClient, userId: string): Effect.Effect<undefined, SqlError, never>;
+/** Sticky blocking is independent of activation and survives unpairing or another identity. */
+export declare function setMemberBlocked(ontology: Ontology, input: {
+    readonly id: string;
+    readonly blocked: boolean;
+}): Effect.Effect<MemberSummary, MemberNotFound, SqlClient.SqlClient>;
+/** Active admitted OIDC members who would lose browser access if email were their only method. */
+export declare function countUsersWithoutEmailIdentity(): Effect.Effect<number, SqlError, SqlClient.SqlClient>;
+/** Established email members who would lose access if SegmentStream became their only method. */
+export declare function countUsersWithoutSegmentStreamIdentity(issuer?: string): Effect.Effect<number, SqlError, SqlClient.SqlClient>;