@volter/twin-planetscale 0.1.0

package/dist/api/src/semantics/index.js

@@ -0,0 +1,381 @@
+// The management lane's handlers, by operationId. Where PlanetScale's reference stops and the twin decides, the comment
+// beside the rule says so.
+import { createHash } from 'node:crypto';
+import { dropAllTables } from "../../../src/planetscale-store.js";
+import { lacks } from "../token-gate.js";
+import { branchSemantics, branchesOf, makeBranch, removeBranch } from "./branches.js";
+import { deployRequestSemantics } from "./deploy-requests.js";
+import { backupPolicySemantics, makeDefaultPolicy } from "./backups.js";
+import { audit, createdById, listAuditLogs, orgOf, personOf } from "./audit.js";
+import { accessOf, actorOf, AVATAR, branchRef, databaseOf, mintId, mintSecret, page, REGION } from "./shared.js";
+const unprocessable = (ctx, message) => ctx.refuse({ status: 422, code: 'unprocessable_entity', message });
+const body = (ctx) => (ctx.body && typeof ctx.body === 'object' && !Array.isArray(ctx.body) ? ctx.body : {});
+const sha256 = (s) => createHash('sha256').update(s).digest('hex');
+/** Which database a password or backup belongs to: a created database's name, or '' for the World's own. */
+const databaseKey = (record) => (record ? String(record.name) : '');
+const newestFirst = (rows) => [...rows].sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)));
+// ── databases ───────────────────────────────────────────────────────────────────────────────
+/** create_database. `name` and `cluster_size` are required (the spec's body schema). Where the reference stops: a name
+ *  the organization already has, and a missing required field, answer 422 naming the field. The database is ready at once
+ *  (manifest.ts, its state machine), with one production branch, `main`. */
+const createDatabase = async (ctx) => {
+    const b = body(ctx);
+    const name = typeof b.name === 'string' ? b.name.trim() : '';
+    if (!name)
+        return unprocessable(ctx, 'name is required');
+    if (typeof b.cluster_size !== 'string' || !b.cluster_size)
+        return unprocessable(ctx, 'cluster_size is required');
+    if (ctx.rowsRaw('Database').some((d) => d.name === name && !d._deleted_at))
+        return unprocessable(ctx, 'Name has already been taken');
+    const org = String(ctx.call.params.organization);
+    const id = mintId(ctx, 'Database', 'db', name);
+    const at = ctx.occurredAt;
+    const record = await ctx.write('Database', id, {
+        id, name, kind: typeof b.kind === 'string' ? b.kind : 'mysql', state: 'pending', ready: false, plan: 'scaler_pro',
+        region: REGION(typeof b.region === 'string' && b.region ? b.region : 'us-east'),
+        default_branch: 'main', branches_count: 1, production_branches_count: 1, development_branches_count: 0, issues_count: 0,
+        sharded: false, created_at: at, updated_at: at, schema_last_updated_at: null,
+        // the rest of what the spec requires of a Database, as a new database has it: one unsharded production branch with
+        // no tables, read-only regions or schema recommendations, and every optional setting off (where the reference
+        // stops: it gives no defaults for these settings, and the twin answers each off)
+        default_branch_shard_count: 1, default_branch_read_only_regions_count: 0, default_branch_table_count: 0, open_schema_recommendations_count: 0,
+        at_backup_restore_branches_limit: false, at_development_branch_usage_limit: false, multiple_admins_required_for_deletion: false,
+        require_approval_for_deploy: false, deletion_protected: false, resizing: false, resize_queued: false, config_changing: false,
+        config_change_queued: false, allow_data_branching: false, foreign_keys_enabled: false, restrict_branch_region: false,
+        prefer_instant: false, insights_raw_queries: false, insights_enabled: false, production_branch_web_console: false,
+        html_url: `https://app.planetscale.com/${org}/${name}`, url: `https://api.planetscale.com/v1/organizations/${org}/databases/${name}`,
+        branches_url: `https://api.planetscale.com/v1/organizations/${org}/databases/${name}/branches`,
+        _cluster_size: b.cluster_size, _organization: org,
+    }, 'database.create');
+    await audit(ctx, org, 'database', 'created', { type: 'Database', id, name });
+    // "a single production branch is created called `main` and acts as the default branch"
+    // (https://planetscale.com/docs/vitess/schema-changes/branching); it turns ready with its database
+    await makeBranch(ctx, record, { name: 'main', parent: null, production: true, parentSchema: [] });
+    // "Our Base plan includes automated backups every 12 hours" (https://planetscale.com/docs/vitess/backups)
+    await makeDefaultPolicy(ctx, name);
+    await grantCreatorAccess(ctx, name);
+    return ctx.reply(record, 201);
+};
+/** Every database access permission, as the service tokens reference lists them
+ *  (https://planetscale.com/docs/api/reference/service-tokens, "Database access permissions"). */
+const DATABASE_ACCESSES = ['read_database', 'write_database', 'delete_database', 'create_branch', 'read_branch', 'delete_branch',
+    'delete_production_branch', 'connect_branch', 'connect_production_branch', 'delete_branch_password', 'delete_production_branch_password',
+    'create_deploy_request', 'read_deploy_request', 'approve_deploy_request', 'create_comment', 'read_comment', 'read_backups', 'write_backups',
+    'delete_backups', 'delete_production_branch_backups', 'restore_backup', 'restore_production_branch_backup', 'write_branch_vschema',
+    'write_production_branch_vschema'];
+/** "When a service token creates a database, it is automatically granted database access permissions for that database"
+ *  (https://planetscale.com/docs/api/service-tokens, "Creating databases with service tokens"): the token that asked gets
+ *  every database access on the new database. A token no lane record names (the World's own) holds everything already. */
+async function grantCreatorAccess(ctx, database) {
+    const id = /^([^:\s]+):/.exec(ctx.call.request.headers.get('authorization') ?? '')?.[1];
+    const token = id === undefined ? undefined : ctx.rowsRaw('ServiceToken').find((t) => t.id === id);
+    if (!token)
+        return;
+    const held = (token.service_token_accesses ?? []);
+    const granted = DATABASE_ACCESSES.filter((access) => !held.some((a) => a.access === access && a.resource_type === 'Database' && a.resource_name === database))
+        .map((access, i) => accessOf(ctx, `${String(token.id)}-${held.length + i + 1}`, access, 'Database', database));
+    await ctx.write('ServiceToken', String(token.id), { ...ctx.own(token), service_token_accesses: [...held, ...granted], updated_at: ctx.occurredAt }, 'service_token.grant');
+}
+const getDatabase = async (ctx) => {
+    const name = String(ctx.call.params.database);
+    const record = ctx.rowsRaw('Database').find((d) => d.name === name && !d._deleted_at);
+    return record ? ctx.reply(ctx.get('Database', String(record.id))) : ctx.notFound('Database', name, 'database');
+};
+/** delete_database. Deleting a database "will: Delete the entire database and all of its branches / Remove all data and
+ *  backups permanently / Disconnect any applications currently connected to the database"
+ *  (https://planetscale.com/docs/vitess/delete-a-database). So its passwords and backups are deleted with it, its tables
+ *  and rows are dropped, and psdb refuses its passwords from then on (the pack root's auth). A name no created database
+ *  has is not found: the World's own database is not deleted through the API (the twin's decision). */
+const deleteDatabase = async (ctx) => {
+    const name = String(ctx.call.params.database);
+    const record = ctx.rowsRaw('Database').find((d) => d.name === name && !d._deleted_at);
+    if (!record)
+        return ctx.notFound('Database', name, 'database');
+    // "Whether deletion protection is enabled for the database" (the spec's update_database_settings): a protected database
+    // is not deleted. Where the reference stops: the refusal's status and words, the twin's 422 naming the rule
+    if (record.deletion_protected === true)
+        return unprocessable(ctx, 'Deletion protection is enabled for this database; turn it off in its settings first');
+    const at = ctx.occurredAt;
+    for (const p of ctx.rowsRaw('DatabaseBranchPassword'))
+        if (p._database === name && p.deleted_at === null)
+            await ctx.write('DatabaseBranchPassword', String(p.id), { ...ctx.own(p), deleted_at: at }, 'password.delete');
+    for (const k of ctx.rowsRaw('Backup'))
+        if (k._database === name && k.deleted_at === null)
+            await ctx.write('Backup', String(k.id), { ...ctx.own(k), deleted_at: at, updated_at: at }, 'backup.delete');
+    for (const b of branchesOf(ctx, name))
+        if (b.name !== 'main')
+            await removeBranch(ctx, name, b);
+    await dropAllTables({ ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: at });
+    for (const b of branchesOf(ctx, name))
+        await ctx.write('DatabaseBranch', String(b.id), { ...ctx.own(b), deleted_at: at, updated_at: at }, 'branch.delete');
+    for (const p of ctx.rowsRaw('BackupPolicy'))
+        if (p._database === name && !p._deleted_at)
+            await ctx.write('BackupPolicy', String(p.id), { ...ctx.own(p), updated_at: at, _deleted_at: at }, 'backup_policy.delete');
+    await ctx.write('Database', String(record.id), { ...ctx.own(record), updated_at: at, _deleted_at: at }, 'database.delete');
+    await audit(ctx, orgOf(ctx), 'database', 'deleted', { type: 'Database', id: String(record.id), name });
+    return new Response(null, { status: 204 });
+};
+/**
+ * update_database_settings: the body's settings, each stored as given (the spec's body; `new_name` renames). The life's
+ * use is `require_approval_for_deploy`: "Whether or not deploy requests must be approved by a database administrator
+ * other than the request creator" (the spec), which the deploy requests read (semantics/deploy-requests.ts). A field of
+ * the body the spec does not have is refused at the edge; the rest are stored with no further effect (the twin's reading).
+ */
+const SETTINGS = {
+    new_name: 'string', automatic_migrations: 'boolean', migration_framework: 'string', migration_table_name: 'string',
+    require_approval_for_deploy: 'boolean', restrict_branch_region: 'boolean', allow_data_branching: 'boolean',
+    allow_foreign_key_constraints: 'boolean', insights_raw_queries: 'boolean', deletion_protected: 'boolean', production_branch_web_console: 'boolean', default_branch: 'string',
+};
+const updateDatabaseSettings = async (ctx) => {
+    const name = String(ctx.call.params.database);
+    const record = ctx.rowsRaw('Database').find((d) => d.name === name && !d._deleted_at);
+    if (!record)
+        return ctx.notFound('Database', name, 'database');
+    const b = body(ctx);
+    const changes = {};
+    for (const [k, v] of Object.entries(b)) {
+        const type = SETTINGS[k];
+        if (type === undefined)
+            return unprocessable(ctx, `${k} is not a database setting`);
+        if (typeof v !== type)
+            return unprocessable(ctx, `${k} must be a ${type}`);
+        if (k === 'new_name')
+            continue;
+        // the default branch must be one of the database's branches (the branching page's "Default branches")
+        if (k === 'default_branch' && !ctx.rowsRaw('DatabaseBranch').some((x) => x._database === name && x.name === v && x.deleted_at === null))
+            return unprocessable(ctx, `default_branch ${String(v)} is not a branch of ${name}`);
+        changes[k === 'allow_foreign_key_constraints' ? 'foreign_keys_enabled' : k] = v;
+    }
+    if (typeof b.new_name === 'string' && b.new_name !== name)
+        return unprocessable(ctx, 'Renaming a database is not modelled by the twin');
+    await ctx.write('Database', String(record.id), { ...ctx.own(record), ...changes, updated_at: ctx.occurredAt }, 'database.update_settings');
+    return ctx.reply(ctx.get('Database', String(record.id)));
+};
+// ── passwords ───────────────────────────────────────────────────────────────────────────────
+const ROLES = ['reader', 'writer', 'admin', 'readwriter'];
+/** create_password. The role is one of the four the spec names. The reference's request body does not mark `role`
+ *  required and gives it no default (https://planetscale.com/docs/api/reference/create_password: "role enum<string> The
+ *  database role of the password (i.e. admin)"; only the response marks it required, and the API states no default).
+ *  When none is sent the twin takes the CLI flag's documented default, inferred for the API: `reader` for a replica
+ *  password, otherwise `admin` (https://planetscale.com/docs/cli/password, --role: "Defaults to `reader` for `--replica`
+ *  and `--read-only-region`, otherwise `admin`"). The answer carries `plain_text`, which "is shown only once and cannot be
+ *  retrieved later" (https://planetscale.com/docs/api/reference/create_password): the twin keeps only its SHA-256, which
+ *  psdb checks a Basic credential against. */
+const createPassword = async (ctx) => {
+    const db = databaseOf(ctx);
+    if (db.refused)
+        return db.refused;
+    const b = body(ctx);
+    // the CLI flag's documented default, inferred for the API, which states none (https://planetscale.com/docs/cli/password,
+    // --role: "Defaults to `reader` for `--replica` and `--read-only-region`, otherwise `admin`")
+    const role = b.role === undefined ? (b.replica === true ? 'reader' : 'admin') : String(b.role);
+    if (!ROLES.includes(role))
+        return unprocessable(ctx, `role must be one of ${ROLES.join(', ')}`);
+    const name = typeof b.name === 'string' && b.name ? b.name : undefined;
+    // a production branch's password needs `connect_production_branch`, any other branch's `connect_branch` ("Connect to a
+    // database branch" / "Connect to a production database branch", https://planetscale.com/docs/api/reference/service-tokens)
+    if (db.branch) {
+        const denied = lacks(ctx, String(db.record.name), db.branch.production === true ? ['connect_production_branch', 'connect_production_read_only_branch'] : ['connect_branch']);
+        if (denied)
+            return denied;
+    }
+    if (b.ttl !== undefined && (!Number.isInteger(b.ttl) || Number(b.ttl) < 0))
+        return unprocessable(ctx, 'ttl must be a whole number of seconds');
+    const ttl = typeof b.ttl === 'number' && b.ttl > 0 ? b.ttl : null;
+    const id = mintId(ctx, 'DatabaseBranchPassword', 'pw', name ?? role);
+    const username = mintSecret('', `username:${ctx.occurredAt}:${id}`, 12).toLowerCase().replace(/[^a-z0-9]/g, 'x');
+    const plainText = mintSecret('pscale_pw_', `password:${ctx.occurredAt}:${id}`, 43);
+    const at = ctx.occurredAt;
+    const record = await ctx.write('DatabaseBranchPassword', id, {
+        id, name: name ?? `${role}-${id.slice(2, 8)}`, role, username, plain_text: null,
+        access_host_url: 'aws.connect.psdb.cloud', access_host_regional_url: 'aws.connect.psdb.cloud', access_host_regional_urls: [],
+        actor: actorOf(ctx), database_branch: branchRef(ctx, db.branch), region: REGION(),
+        // "Time to live (in seconds) for the password. The password will be invalid when TTL has passed" (the spec)
+        created_at: at, deleted_at: null, expires_at: ttl === null ? null : new Date(Date.parse(at) + ttl * 1000).toISOString(), expired: false, last_used_at: null, replica: b.replica === true,
+        direct_vtgate_addresses: [], read_only_region: false,
+        renewable: false, ttl_seconds: ttl, cidrs: Array.isArray(b.cidrs) ? b.cidrs : null, direct_vtgate: b.direct_vtgate === true,
+        _database: databaseKey(db.record), _secret_sha256: sha256(plainText),
+    }, 'password.create');
+    if (db.record)
+        await audit(ctx, orgOf(ctx), 'database_branch_password', 'created', { type: 'DatabaseBranchPassword', id, name: String(record.name) }, { auditable: { type: 'Database', id: String(db.record.id), name: String(db.record.name) } });
+    return ctx.reply({ ...record, plain_text: plainText }, 201);
+};
+const passwordsOf = (ctx, record) => ctx.rowsRaw('DatabaseBranchPassword').filter((p) => p._database === databaseKey(record) && p.database_branch?.name === ctx.call.params.branch);
+const listPasswords = async (ctx) => {
+    const db = databaseOf(ctx);
+    if (db.refused)
+        return db.refused;
+    const q = new URL(ctx.call.request.url).searchParams.get('q');
+    const rows = passwordsOf(ctx, db.record).filter((p) => p.deleted_at === null && (!q || String(p.name).includes(q)));
+    return page(ctx, newestFirst(rows).map((p) => ctx.get('DatabaseBranchPassword', String(p.id))));
+};
+const getPassword = async (ctx) => {
+    const db = databaseOf(ctx);
+    if (db.refused)
+        return db.refused;
+    const p = passwordsOf(ctx, db.record).find((x) => x.id === ctx.id && x.deleted_at === null);
+    return p ? ctx.reply(ctx.get('DatabaseBranchPassword', String(p.id))) : ctx.notFound('DatabaseBranchPassword', String(ctx.id), 'id');
+};
+/** delete_password: the password stops authenticating at once (psdb reads `deleted_at`). */
+const deletePassword = async (ctx) => {
+    const db = databaseOf(ctx);
+    if (db.refused)
+        return db.refused;
+    const p = passwordsOf(ctx, db.record).find((x) => x.id === ctx.id && x.deleted_at === null);
+    if (!p)
+        return ctx.notFound('DatabaseBranchPassword', String(ctx.id), 'id');
+    await ctx.write('DatabaseBranchPassword', String(p.id), { ...ctx.own(p), deleted_at: ctx.occurredAt }, 'password.delete');
+    if (db.record)
+        await audit(ctx, orgOf(ctx), 'database_branch_password', 'deleted', { type: 'DatabaseBranchPassword', id: String(p.id), name: String(p.name) }, { auditable: { type: 'Database', id: String(db.record.id), name: String(db.record.name) } });
+    return new Response(null, { status: 204 });
+};
+// ── backups ─────────────────────────────────────────────────────────────────────────────────
+// From PlanetScale's API reference: create takes `name`, `retention_unit` (hour, day, week, month, year), `retention_value`
+// ("Value between `1` and `1000`") and `emergency` ("Emergency backups are only supported for PostgreSQL databases"), and
+// answers 201 with the backup, `pending` (its example), then polled with get_backup; the list takes `all` ("Whether to include all backups, including deleted ones"), `state`,
+// `policy`, `from`, `to`, `running_at` and `production`, paged by `page` and `per_page`. Where the reference stops and the
+// twin decides: a backup runs and completes on the World clock (manifest.ts, semantics/time.ts), its size the bytes of the
+// branch's stored rows when it completes, its storage cost 0, expiring its retention (default 7 days) after it completes
+// (the backups pages do not say from when retention counts), on no backup policy; the list is newest first; a deleted backup is
+// still read by its id (with its deleted_at) and listed only with `all`. Dub's backup cron
+// (apps/web/app/(ee)/api/cron/trigger-backup) creates one four times a day.
+const UNITS = { hour: 3_600_000, day: 86_400_000, week: 604_800_000, month: 2_592_000_000, year: 31_536_000_000 };
+/** The bytes of the branch's stored rows: what a backup of it holds. */
+export function branchBytes(ctx) {
+    return ctx.tree().filter((r) => r.type === 'row' && r.deleted !== true).map((r) => ctx.own(r))
+        .filter((f) => f.gone !== true && f.deleted !== true).reduce((n, f) => n + Buffer.byteLength(JSON.stringify(f.cells ?? {})), 0);
+}
+const backupsOf = (ctx, record) => ctx.rowsRaw('Backup').filter((k) => (k._database ?? '') === databaseKey(record));
+const createBackup = async (ctx) => {
+    const db = databaseOf(ctx);
+    if (db.refused)
+        return db.refused;
+    const b = body(ctx);
+    const unit = b.retention_unit === undefined ? 'day' : String(b.retention_unit);
+    const value = b.retention_value === undefined ? 7 : Number(b.retention_value);
+    if (!(unit in UNITS))
+        return unprocessable(ctx, 'retention_unit must be one of hour, day, week, month, year');
+    if (!Number.isInteger(value) || value < 1 || value > 1000)
+        return unprocessable(ctx, 'retention_value must be between 1 and 1000');
+    if (b.emergency === true)
+        return unprocessable(ctx, 'Emergency backups are only supported for PostgreSQL databases');
+    const at = ctx.occurredAt;
+    const n = backupsOf(ctx, db.record).length + 1;
+    const id = mintId(ctx, 'Backup', 'bk', String(b.name ?? ''));
+    const record = await ctx.write('Backup', id, {
+        id, name: typeof b.name === 'string' && b.name ? b.name : `backup-${n}`, state: 'pending', size: 0, estimated_storage_cost: 0,
+        created_at: at, updated_at: at, started_at: null, completed_at: null, expires_at: null, deleted_at: null,
+        pvc_size: 0, uncompressed_size: 0, protected: false, required: false, restored_branches: [],
+        actor: actorOf(ctx), backup_policy: null, schema_snapshot: null, database_branch: branchRef(ctx, db.branch),
+        _database: databaseKey(db.record), _retention_ms: value * UNITS[unit],
+    }, 'backup.create');
+    return ctx.reply(record, 201);
+};
+const listBackups = async (ctx) => {
+    const db = databaseOf(ctx);
+    if (db.refused)
+        return db.refused;
+    const q = new URL(ctx.call.request.url).searchParams;
+    const state = q.get('state');
+    const all = q.get('all') === 'true';
+    const time = (v) => (typeof v === 'string' ? Date.parse(v) : NaN);
+    const from = q.has('from') ? time(q.get('from')) : undefined;
+    const to = q.has('to') ? time(q.get('to')) : undefined;
+    const [runFrom, runTo] = q.has('running_at') ? (q.get('running_at') ?? '').split('..').map(time) : [undefined, undefined];
+    if ([from, to, runFrom].some((v) => v !== undefined && Number.isNaN(v)) || (runTo !== undefined && Number.isNaN(runTo)))
+        return unprocessable(ctx, 'from, to and running_at take ISO-8601 times (running_at as <from>..<to>)');
+    const rows = backupsOf(ctx, db.record).filter((k) => {
+        const started = time(k.started_at);
+        const completed = time(k.completed_at);
+        return (all || k.deleted_at === null) && (!state || k.state === state)
+            && (!q.has('policy') || k.backup_policy?.id === q.get('policy'))
+            && (!q.has('production') || q.get('production') === 'true')
+            && (from === undefined || started > from) && (to === undefined || started < to)
+            && (runFrom === undefined || (started <= (runTo ?? runFrom) && completed >= runFrom));
+    });
+    // newest first, by when each was made
+    const newest = rows.map((k, i) => ({ k, i })).sort((x, y) => String(y.k.created_at).localeCompare(String(x.k.created_at)) || y.i - x.i).map((x) => x.k);
+    return page(ctx, newest.map((k) => ctx.get('Backup', String(k.id))));
+};
+const getBackup = async (ctx) => {
+    const db = databaseOf(ctx);
+    if (db.refused)
+        return db.refused;
+    const k = backupsOf(ctx, db.record).find((x) => x.id === ctx.id);
+    return k ? ctx.reply(ctx.get('Backup', String(k.id))) : ctx.notFound('Backup', String(ctx.id), 'id');
+};
+const deleteBackup = async (ctx) => {
+    const db = databaseOf(ctx);
+    if (db.refused)
+        return db.refused;
+    const k = backupsOf(ctx, db.record).find((x) => x.id === ctx.id && x.deleted_at === null);
+    if (!k)
+        return ctx.notFound('Backup', String(ctx.id), 'id');
+    await ctx.write('Backup', String(k.id), { ...ctx.own(k), deleted_at: ctx.occurredAt, updated_at: ctx.occurredAt }, 'backup.delete');
+    return new Response(null, { status: 204 });
+};
+// ── service tokens ──────────────────────────────────────────────────────────────────────────
+/** A service token as the API answers it, its secret left out ("The plaintext token. Available only after create."). */
+export async function makeServiceToken(ctx, name, accesses, createdBy, organization = orgOf(ctx), ttl) {
+    const id = mintId(ctx, 'ServiceToken', '', name);
+    const token = mintSecret('pscale_tkn_', `token:${ctx.occurredAt}:${id}`, 43);
+    const at = ctx.occurredAt;
+    const record = await ctx.write('ServiceToken', id, {
+        id, name, display_name: name, token: null, plain_text_refresh_token: null, avatar_url: AVATAR,
+        // "Time to live (in seconds) for the service token. The token will be invalid when TTL has passed" (the spec)
+        created_at: at, updated_at: at, expires_at: ttl ? new Date(Date.parse(at) + ttl * 1000).toISOString() : null, last_used_at: null,
+        actor_id: null, actor_display_name: null, actor_type: null, oauth_accesses_by_resource: null,
+        service_token_accesses: accesses.map((a, i) => accessOf(ctx, `${id}-${i + 1}`, a.access, a.resource_type === 'Database' ? 'Database' : 'Organization', a.resource_name)),
+        // who made it on the settings page: a person cannot approve a deploy request a token they made created
+        // (https://planetscale.com/docs/api/reference/service-tokens, "Service tokens and deploy requests approvals")
+        _secret_sha256: sha256(token), ...(createdBy ? { _created_by: createdBy } : {}),
+    }, 'service_token.create');
+    await audit(ctx, organization, 'service_token', 'created', { type: 'ServiceToken', id, name }, createdBy ? { actor: personOf(createdBy, createdById(createdBy)) } : {});
+    return { record, token };
+}
+/** create_service_token: a token with no accesses; they are granted on the organization's settings page (manifest.ts,
+ *  `screens`), since no operation of the API grants one. */
+const createServiceToken = async (ctx) => {
+    const b = body(ctx);
+    const name = typeof b.name === 'string' && b.name ? b.name : 'service-token';
+    if (b.ttl !== undefined && (!Number.isInteger(b.ttl) || Number(b.ttl) < 1))
+        return unprocessable(ctx, 'ttl must be a whole number of seconds');
+    const { record, token } = await makeServiceToken(ctx, name, [], undefined, orgOf(ctx), typeof b.ttl === 'number' ? b.ttl : undefined);
+    return ctx.reply({ ...record, token }, 200);
+};
+const listServiceTokens = async (ctx) => page(ctx, ctx.rowsRaw('ServiceToken').filter((t) => !t._deleted_at).map((t) => ctx.get('ServiceToken', String(t.id))));
+/** A service token deleted: its ID and token stop authenticating at once (token-gate.ts refuses a deleted token as any
+ *  token PlanetScale does not hold). "You can delete a service token at any time from the service token detail page"
+ *  (https://planetscale.com/docs/cli/service-tokens); the API's delete_service_token does the same. */
+export async function removeServiceToken(ctx, token, organization, actor) {
+    await ctx.write('ServiceToken', String(token.id), { ...ctx.own(token), updated_at: ctx.occurredAt, _deleted_at: ctx.occurredAt }, 'service_token.delete');
+    await audit(ctx, organization, 'service_token', 'deleted', { type: 'ServiceToken', id: String(token.id), name: String(token.display_name) }, actor ? { actor } : {});
+}
+const deleteServiceToken = async (ctx) => {
+    const token = ctx.rowsRaw('ServiceToken').find((t) => t.id === ctx.call.params.id && !t._deleted_at);
+    if (!token)
+        return ctx.notFound('ServiceToken', String(ctx.call.params.id), 'id');
+    await removeServiceToken(ctx, token, orgOf(ctx));
+    return new Response(null, { status: 204 });
+};
+export const apiSemantics = {
+    ...branchSemantics,
+    ...deployRequestSemantics,
+    ...backupPolicySemantics,
+    list_audit_logs: listAuditLogs,
+    create_database: createDatabase,
+    get_database: getDatabase,
+    update_database_settings: updateDatabaseSettings,
+    delete_database: deleteDatabase,
+    create_password: createPassword,
+    list_passwords: listPasswords,
+    get_password: getPassword,
+    delete_password: deletePassword,
+    create_backup: createBackup,
+    list_backups: listBackups,
+    get_backup: getBackup,
+    delete_backup: deleteBackup,
+    create_service_token: createServiceToken,
+    list_service_tokens: listServiceTokens,
+    delete_service_token: deleteServiceToken,
+};