@tula-tech/contract 0.0.0-stage → 0.1.1

package/dist/error-codes.d.ts

@@ -0,0 +1,386 @@
+/**
+* The error codes of the public contract, as plain data.
+*
+* This module has no dependencies (no Zod), so an SDK can import it from
+* `@tula-tech/contract/error-codes` without adding a schema library to an application's bundle. The
+* Zod schemas built on these codes live in `./errors`.
+*/
+/** Definition of one contract error code: its HTTP status and default (English) message. */
+interface ErrorDefinition {
+	/** HTTP status the API responds with for this code. */
+	readonly status: number;
+	/** Default human-readable message; SDKs may localize by `code`. */
+	readonly message: string;
+}
+/**
+* Every machine-readable error code the API can return, keyed `area.reason`.
+*
+* Codes are part of the public contract: SDKs switch on them and translate them, so they are
+* append-only. Removing or renaming one is a breaking change.
+*
+* Sign-up deliberately has no "email already taken" code: an existing address still receives
+* `needs_email_verification` (and a notice email) so sign-up can't be used to enumerate accounts.
+*/
+declare const ERROR_DEFINITIONS: {
+	readonly "auth.invalid_credentials": {
+		readonly status: 401;
+		readonly message: "The email or password is incorrect.";
+	};
+	readonly "auth.unauthenticated": {
+		readonly status: 401;
+		readonly message: "You need to sign in to do that.";
+	};
+	readonly "auth.invalid_key": {
+		readonly status: 401;
+		readonly message: "The API key is missing, invalid or revoked.";
+	};
+	readonly "auth.forbidden": {
+		readonly status: 403;
+		readonly message: "You do not have permission to do that.";
+	};
+	readonly "auth.user_banned": {
+		readonly status: 403;
+		readonly message: "This account has been disabled.";
+	};
+	readonly "auth.method_disabled": {
+		readonly status: 403;
+		readonly message: "This sign-in method is not available.";
+	};
+	readonly "auth.step_up_required": {
+		readonly status: 403;
+		readonly message: "Confirm it is you to continue.";
+	};
+	readonly "flow.not_found": {
+		readonly status: 404;
+		readonly message: "This attempt does not exist or has expired.";
+	};
+	readonly "flow.invalid_step": {
+		readonly status: 409;
+		readonly message: "That action is not valid at this step. Please start again.";
+	};
+	readonly "email.invalid": {
+		readonly status: 422;
+		readonly message: "Enter a valid email address.";
+	};
+	readonly "email.already_set": {
+		readonly status: 409;
+		readonly message: "This account already has an email address.";
+	};
+	readonly "password.too_short": {
+		readonly status: 422;
+		readonly message: "Password is too short.";
+	};
+	readonly "password.too_long": {
+		readonly status: 422;
+		readonly message: "Password is too long.";
+	};
+	readonly "password.missing_lowercase": {
+		readonly status: 422;
+		readonly message: "Add a lowercase letter.";
+	};
+	readonly "password.missing_uppercase": {
+		readonly status: 422;
+		readonly message: "Add an uppercase letter.";
+	};
+	readonly "password.missing_number": {
+		readonly status: 422;
+		readonly message: "Add a number.";
+	};
+	readonly "password.missing_special": {
+		readonly status: 422;
+		readonly message: "Add a special character.";
+	};
+	readonly "password.too_few_character_classes": {
+		readonly status: 422;
+		readonly message: "Use a wider mix of letters, numbers and symbols.";
+	};
+	readonly "password.contains_user_info": {
+		readonly status: 422;
+		readonly message: "Password must not contain your name or email.";
+	};
+	readonly "password.common": {
+		readonly status: 422;
+		readonly message: "This password is too common.";
+	};
+	readonly "password.breached": {
+		readonly status: 422;
+		readonly message: "This password appeared in a data breach. Choose a different one.";
+	};
+	readonly "password.repeated_characters": {
+		readonly status: 422;
+		readonly message: "Avoid repeating the same character.";
+	};
+	readonly "password.sequence": {
+		readonly status: 422;
+		readonly message: "Avoid sequences like \"abcd\" or \"1234\".";
+	};
+	readonly "password.reused": {
+		readonly status: 422;
+		readonly message: "You have used this password recently. Choose a different one.";
+	};
+	readonly "password.not_set": {
+		readonly status: 409;
+		readonly message: "This account has no password yet. Use \"forgot password\" to set one.";
+	};
+	readonly "verification.invalid_code": {
+		readonly status: 422;
+		readonly message: "That code is incorrect.";
+	};
+	readonly "verification.expired": {
+		readonly status: 410;
+		readonly message: "That code has expired. Request a new one.";
+	};
+	readonly "verification.too_many_attempts": {
+		readonly status: 429;
+		readonly message: "Too many incorrect codes. Request a new one.";
+	};
+	readonly "verification.different_browser": {
+		readonly status: 409;
+		readonly message: "Open this link in the browser where you started signing in, or enter the code from the email there.";
+	};
+	readonly "mfa.invalid_code": {
+		readonly status: 422;
+		readonly message: "That code is incorrect.";
+	};
+	readonly "mfa.already_enabled": {
+		readonly status: 409;
+		readonly message: "Two-step verification is already on for this account.";
+	};
+	readonly "mfa.not_enabled": {
+		readonly status: 409;
+		readonly message: "Two-step verification is not on for this account.";
+	};
+	readonly "mfa.enrolment_expired": {
+		readonly status: 410;
+		readonly message: "This setup has expired. Start again.";
+	};
+	readonly "mfa.not_available": {
+		readonly status: 403;
+		readonly message: "Two-step verification is not available for this app.";
+	};
+	readonly "mfa.enrolment_needs_other_sign_in": {
+		readonly status: 403;
+		readonly message: "Sign in another way to set up two-step verification.";
+	};
+	readonly "mfa.needs_other_sign_in": {
+		readonly status: 403;
+		readonly message: "Sign in another way. A texted code cannot be both steps.";
+	};
+	readonly "mfa.sms_not_allowed": {
+		readonly status: 409;
+		readonly message: "This account already has a stronger second step than a texted code.";
+	};
+	readonly "mfa.phone_number_required": {
+		readonly status: 409;
+		readonly message: "Add a phone number to your account first.";
+	};
+	readonly "mfa.required_by_policy": {
+		readonly status: 403;
+		readonly message: "This app requires two-step verification. It cannot be turned off.";
+	};
+	readonly "oauth.access_denied": {
+		readonly status: 403;
+		readonly message: "Sign-in was cancelled. Try again or choose another way to sign in.";
+	};
+	readonly "oauth.provider_error": {
+		readonly status: 502;
+		readonly message: "The sign-in provider could not complete the request. Try again.";
+	};
+	readonly "oauth.state_invalid": {
+		readonly status: 400;
+		readonly message: "This sign-in could not be completed. Start again.";
+	};
+	readonly "oauth.ticket_invalid": {
+		readonly status: 410;
+		readonly message: "This sign-in has expired. Start again.";
+	};
+	readonly "oauth.different_browser": {
+		readonly status: 409;
+		readonly message: "Finish signing in in the browser where you started, or start again here.";
+	};
+	readonly "oauth.email_missing": {
+		readonly status: 403;
+		readonly message: "This provider did not share an email address. Allow access to your email and try again.";
+	};
+	readonly "oauth.email_unverified": {
+		readonly status: 403;
+		readonly message: "Your email address is not verified with this provider. Verify it there and try again.";
+	};
+	readonly "oauth.account_exists": {
+		readonly status: 409;
+		readonly message: "An account with this email already exists. Sign in the way you usually do, then connect this provider from your account.";
+	};
+	readonly "oauth.identity_in_use": {
+		readonly status: 409;
+		readonly message: "This provider account is already connected to another user.";
+	};
+	readonly "oauth.already_linked": {
+		readonly status: 409;
+		readonly message: "An account of this provider is already connected. Disconnect it first.";
+	};
+	readonly "identity.last_sign_in_method": {
+		readonly status: 409;
+		readonly message: "This is your only way to sign in. Add a password or connect another account first.";
+	};
+	readonly "webhook.url_not_allowed": {
+		readonly status: 422;
+		readonly message: "The server cannot deliver to that address.";
+	};
+	readonly "webhook.cannot_redeliver": {
+		readonly status: 409;
+		readonly message: "This delivery cannot be sent again.";
+	};
+	readonly "webhook.rotation_refused": {
+		readonly status: 409;
+		readonly message: "The signing secret cannot be changed now.";
+	};
+	readonly "hook.denied": {
+		readonly status: 403;
+		readonly message: "This was not allowed.";
+	};
+	readonly "hook.unavailable": {
+		readonly status: 503;
+		readonly message: "This is unavailable right now. Try again later.";
+	};
+	readonly "hook.url_not_allowed": {
+		readonly status: 422;
+		readonly message: "The server cannot call that address.";
+	};
+	readonly "passkey.registration_failed": {
+		readonly status: 422;
+		readonly message: "That passkey could not be saved. Try again.";
+	};
+	readonly "passkey.already_registered": {
+		readonly status: 409;
+		readonly message: "This passkey is already saved to an account.";
+	};
+	readonly "passkey.limit_reached": {
+		readonly status: 409;
+		readonly message: "You have reached the number of passkeys an account can have. Remove one first.";
+	};
+	readonly "passkey.last_sign_in_method": {
+		readonly status: 409;
+		readonly message: "This is your only way to sign in. Add a password or connect an account first.";
+	};
+	readonly "phone.invalid": {
+		readonly status: 422;
+		readonly message: "Enter a phone number with its country code, such as +14155550100.";
+	};
+	readonly "sms.disabled": {
+		readonly status: 403;
+		readonly message: "Text messages are not available.";
+	};
+	readonly "sms.country_not_allowed": {
+		readonly status: 422;
+		readonly message: "Text messages cannot be sent to that country.";
+	};
+	readonly "sms.unavailable": {
+		readonly status: 503;
+		readonly message: "The text message could not be sent. Try again later.";
+	};
+	readonly "session.invalid_token": {
+		readonly status: 401;
+		readonly message: "Your session is invalid. Sign in again.";
+	};
+	readonly "session.expired": {
+		readonly status: 401;
+		readonly message: "Your session has expired. Sign in again.";
+	};
+	readonly "session.revoked": {
+		readonly status: 401;
+		readonly message: "Your session was signed out. Sign in again.";
+	};
+	readonly "session.reuse_detected": {
+		readonly status: 401;
+		readonly message: "For your security this session was signed out. Sign in again.";
+	};
+	readonly "session.limit_reached": {
+		readonly status: 403;
+		readonly message: "You are signed in on too many devices. Sign out on another device, or reset your password to sign out everywhere, then try again.";
+	};
+	readonly "device.proof_invalid": {
+		readonly status: 401;
+		readonly message: "This session is bound to a device key, and the request did not prove that key.";
+	};
+	readonly "device.nonce_required": {
+		readonly status: 400;
+		readonly message: "The proof needs a fresh nonce. Send the request again with the nonce provided.";
+	};
+	readonly "device.binding_not_supported": {
+		readonly status: 400;
+		readonly message: "A session of this kind of client cannot be bound to a device key.";
+	};
+	readonly "device.binding_required": {
+		readonly status: 400;
+		readonly message: "Signing in here needs a device key.";
+	};
+	readonly rate_limited: {
+		readonly status: 429;
+		readonly message: "Too many requests. Try again shortly.";
+	};
+	readonly "request.malformed": {
+		readonly status: 400;
+		readonly message: "The request could not be read.";
+	};
+	readonly "request.too_large": {
+		readonly status: 413;
+		readonly message: "The request body is too large.";
+	};
+	readonly "request.origin_not_allowed": {
+		readonly status: 403;
+		readonly message: "This origin is not allowed to sign in to this app.";
+	};
+	readonly "request.redirect_not_allowed": {
+		readonly status: 400;
+		readonly message: "This redirect URL is not allowed for this app.";
+	};
+	readonly "validation.failed": {
+		readonly status: 422;
+		readonly message: "Some fields are invalid.";
+	};
+	readonly "resource.not_found": {
+		readonly status: 404;
+		readonly message: "The requested resource does not exist.";
+	};
+	readonly "resource.conflict": {
+		readonly status: 409;
+		readonly message: "The resource conflicts with existing data.";
+	};
+	readonly "precondition.required": {
+		readonly status: 428;
+		readonly message: "Send the revision you are changing in an If-Match header.";
+	};
+	readonly "precondition.failed": {
+		readonly status: 412;
+		readonly message: "The resource changed since you read it. Read it again and retry.";
+	};
+	readonly not_implemented: {
+		readonly status: 501;
+		readonly message: "This capability is not available yet.";
+	};
+	readonly "service.unavailable": {
+		readonly status: 503;
+		readonly message: "The service is temporarily unavailable. Try again shortly.";
+	};
+	readonly internal: {
+		readonly status: 500;
+		readonly message: "Something went wrong on our side.";
+	};
+};
+/** A stable, machine-readable error code (e.g. `password.too_short`). */
+type ErrorCode = keyof typeof ERROR_DEFINITIONS;
+/** All error codes, for building enums in generated clients. */
+declare const ERROR_CODES: [ErrorCode, ...ErrorCode[]];
+/**
+* Look up the HTTP status and default message for an error code.
+*
+* @param code - The contract error code.
+* @returns Its definition.
+*
+* @example
+* ```ts
+* errorDefinition('password.too_short').status // 422
+* ```
+*/
+declare function errorDefinition(code: ErrorCode): ErrorDefinition;
+export { ERROR_CODES, ERROR_DEFINITIONS, ErrorCode, ErrorDefinition, errorDefinition };

package/dist/error-codes.js

@@ -0,0 +1,10 @@
+import {
+  ERROR_DEFINITIONS2,
+  ERROR_CODES2,
+  errorDefinition2
+} from "./shared/chunk-cce3bhet.js";
+export {
+  ERROR_CODES2 as ERROR_CODES,
+  ERROR_DEFINITIONS2 as ERROR_DEFINITIONS,
+  errorDefinition2 as errorDefinition
+};

package/dist/event-types.d.ts

@@ -0,0 +1,107 @@
+/**
+* Everything the API records. Each entry is written to the event outbox (for webhooks) and to
+* the audit log, in the same database transaction as the change it describes.
+*
+* A session ends with exactly one of `session.revoked` (its `reason` says why) or
+* `session.reuse_detected` (a rotated refresh token was replayed, so the session was revoked as
+* possibly stolen).
+*
+* A new type needs three things, and a test fails for each one that is missing: its name here
+* (and in {@link EVENT_TARGET_TYPES}), a `data` schema in `EVENT_DATA_SCHEMAS` and an example
+* in `EVENT_FIXTURES`.
+*
+* @example
+* ```ts
+* import { ACTIVITY_TYPES, type ActivityType } from '@tula-tech/contract/event-types'
+*
+* function isKnown(type: string): type is ActivityType {
+*   return (ACTIVITY_TYPES as readonly string[]).includes(type)
+* }
+* ```
+*/
+declare const ACTIVITY_TYPES: readonly ["user.created", "user.email_verified", "user.banned", "user.unbanned", "user.deleted", "user.password_changed", "user.mfa_enabled", "user.mfa_disabled", "user.backup_codes_regenerated", "user.backup_code_used", "user.identity_linked", "user.identity_unlinked", "user.email_added", "user.passkey_added", "user.passkey_renamed", "user.passkey_removed", "user.passkey_counter_regressed", "user.phone_number_added", "user.phone_number_removed", "user.sms_factor_enabled", "user.sms_factor_removed", "session.created", "session.revoked", "session.reuse_detected", "session.stepped_up", "session.refresh_proof_refused", "api_key.created", "api_key.revoked", "signing_key.rotated", "environment.settings_updated", "oauth_provider.updated", "oauth_provider.deleted", "webhook_endpoint.created", "webhook_endpoint.updated", "webhook_endpoint.deleted", "webhook_endpoint.disabled", "webhook_endpoint.secret_rotated", "webhook_endpoint.previous_secret_revoked", "hook.created", "hook.updated", "hook.deleted", "native_app.created", "native_app.updated", "native_app.deleted", "proposal.created", "proposal.approved", "proposal.executed", "proposal.failed", "sign_in_test.started", "sign_in_test.finished"];
+/** A recorded action type: one of {@link ACTIVITY_TYPES}. */
+type ActivityType = (typeof ACTIVITY_TYPES)[number];
+/**
+* The version of the event payloads: the `schemaVersion` of every event.
+*
+* Within a version a payload only grows: a later server may add an event type, a field or an
+* enum value, so a receiver ignores what it does not know. Removing or renaming a field, or
+* changing what one means, is a new version.
+*
+* @example
+* ```ts
+* if (event.schemaVersion !== EVENT_SCHEMA_VERSION) {
+*   // Written by a server with a newer payload format than this code was built for.
+* }
+* ```
+*/
+declare const EVENT_SCHEMA_VERSION = 1;
+/**
+* What each event is about: the `target.type` of its payload. `target.id` is that thing's id.
+*
+* An event about a user's credentials targets the `user` (the passkey or session concerned
+* is named in `data`); an OAuth provider's credentials belong to the `environment`. A webhook
+* endpoint has an id of its own, as an API key does, so it is its own kind of target, and so
+* are a hook, a native app and a proposal (what a proposal would change is in its `data`).
+*
+* @example
+* ```ts
+* EVENT_TARGET_TYPES['session.revoked'] // 'session'
+* ```
+*/
+declare const EVENT_TARGET_TYPES: {
+	readonly "user.created": "user";
+	readonly "user.email_verified": "user";
+	readonly "user.banned": "user";
+	readonly "user.unbanned": "user";
+	readonly "user.deleted": "user";
+	readonly "user.password_changed": "user";
+	readonly "user.mfa_enabled": "user";
+	readonly "user.mfa_disabled": "user";
+	readonly "user.backup_codes_regenerated": "user";
+	readonly "user.backup_code_used": "user";
+	readonly "user.identity_linked": "user";
+	readonly "user.email_added": "user";
+	readonly "user.identity_unlinked": "user";
+	readonly "user.passkey_added": "user";
+	readonly "user.passkey_renamed": "user";
+	readonly "user.passkey_removed": "user";
+	readonly "user.passkey_counter_regressed": "user";
+	readonly "user.phone_number_added": "user";
+	readonly "user.phone_number_removed": "user";
+	readonly "user.sms_factor_enabled": "user";
+	readonly "user.sms_factor_removed": "user";
+	readonly "session.created": "session";
+	readonly "session.revoked": "session";
+	readonly "session.reuse_detected": "session";
+	readonly "session.stepped_up": "session";
+	readonly "session.refresh_proof_refused": "session";
+	readonly "api_key.created": "api_key";
+	readonly "api_key.revoked": "api_key";
+	readonly "signing_key.rotated": "signing_key";
+	readonly "environment.settings_updated": "environment";
+	readonly "oauth_provider.updated": "environment";
+	readonly "oauth_provider.deleted": "environment";
+	readonly "webhook_endpoint.created": "webhook_endpoint";
+	readonly "webhook_endpoint.updated": "webhook_endpoint";
+	readonly "webhook_endpoint.deleted": "webhook_endpoint";
+	readonly "webhook_endpoint.disabled": "webhook_endpoint";
+	readonly "webhook_endpoint.secret_rotated": "webhook_endpoint";
+	readonly "webhook_endpoint.previous_secret_revoked": "webhook_endpoint";
+	readonly "hook.created": "hook";
+	readonly "hook.updated": "hook";
+	readonly "hook.deleted": "hook";
+	readonly "native_app.created": "native_app";
+	readonly "native_app.updated": "native_app";
+	readonly "native_app.deleted": "native_app";
+	readonly "proposal.created": "proposal";
+	readonly "proposal.approved": "proposal";
+	readonly "proposal.executed": "proposal";
+	readonly "proposal.failed": "proposal";
+	readonly "sign_in_test.started": "environment";
+	readonly "sign_in_test.finished": "environment";
+};
+/** What an event of type `T` is about. */
+type EventTargetType<T extends ActivityType = ActivityType> = (typeof EVENT_TARGET_TYPES)[T];
+export { ACTIVITY_TYPES, ActivityType, EVENT_SCHEMA_VERSION, EVENT_TARGET_TYPES, EventTargetType };

package/dist/event-types.js

@@ -0,0 +1,10 @@
+import {
+  ACTIVITY_TYPES2,
+  EVENT_SCHEMA_VERSION2,
+  EVENT_TARGET_TYPES2
+} from "./shared/chunk-7yqzghgm.js";
+export {
+  ACTIVITY_TYPES2 as ACTIVITY_TYPES,
+  EVENT_SCHEMA_VERSION2 as EVENT_SCHEMA_VERSION,
+  EVENT_TARGET_TYPES2 as EVENT_TARGET_TYPES
+};