@tula-tech/contract 0.0.0-stage → 0.1.1

package/dist/headers.d.ts

@@ -0,0 +1,223 @@
+/**
+* Names of the request headers the client API reads (the key, the client kind, the session
+* profile, an attempt's secret), of the response header the admin factor
+* reset answers with, and of the parameters an emailed sign-in link and an OAuth sign-in carry
+* in a URL fragment.
+*
+* This module has no dependencies (no Zod), so an SDK can import it from
+* `@tula-tech/contract/headers` without adding anything to an application's bundle.
+*/
+/**
+* Request header carrying the publishable key (`tula_pk_<env>_…`) on every `/v1/client/*` call.
+* It names the project and environment the request belongs to.
+*
+* @example
+* ```ts
+* await fetch(`${api}/v1/client/config`, { headers: { [PUBLISHABLE_KEY_HEADER]: key } })
+* ```
+*/
+declare const PUBLISHABLE_KEY_HEADER = "x-tula-publishable-key";
+/**
+* Request header naming the kind of client (`web`, `ios`, `android` or `server`), read when an
+* attempt starts. It decides how the refresh token is delivered when the flow completes: an
+* httpOnly cookie for `web` (the default), the response body for the others.
+*
+* @example
+* ```ts
+* await fetch(`${api}/v1/client/sign-ins`, {
+*   method: 'POST',
+*   headers: { [CLIENT_HEADER]: 'ios', ...others },
+*   body: JSON.stringify({ identifier }),
+* })
+* ```
+*/
+declare const CLIENT_HEADER = "x-tula-client";
+/**
+* Request header naming the session profile a client would like, read when an attempt starts
+* (next to {@link CLIENT_HEADER}). Optional.
+*
+* It is a request, not a choice: the session gets that profile only when the environment marks
+* it `clientSelectable`. Any other name (unknown, not offered, a built-in) is ignored and the
+* session gets the profile of its client kind, so a client can never give itself a
+* longer-lived session than the operator offered (ADR 0028).
+*
+* @example
+* ```ts
+* await fetch(`${api}/v1/client/sign-ins`, {
+*   method: 'POST',
+*   headers: { [SESSION_PROFILE_HEADER]: 'admin', ...others },
+*   body: JSON.stringify({ identifier }),
+* })
+* ```
+*/
+declare const SESSION_PROFILE_HEADER = "x-tula-session-profile";
+/**
+* Request header carrying an attempt's secret.
+*
+* Starting a sign-up, sign-in or password reset returns `attemptSecret` once; every later call
+* on that attempt sends it in this header. Without it (or with another attempt's) the attempt
+* answers `flow.not_found`, so an attempt id seen in a URL, a log or an email is useless alone.
+*
+* @example
+* ```ts
+* await fetch(`${api}/v1/client/sign-ins/${attempt.id}/password`, {
+*   method: 'POST',
+*   headers: { [FLOW_ATTEMPT_HEADER]: attempt.attemptSecret, ...others },
+*   body: JSON.stringify({ password }),
+* })
+* ```
+*/
+declare const FLOW_ATTEMPT_HEADER = "x-tula-attempt";
+/**
+* Response header of the admin factor reset (`DELETE /v1/admin/users/:userId/factors`):
+* `true` or `false`, whether the user can still sign in with what they have left.
+*
+* The reset removes the user's passkeys together with their authenticator and backup codes.
+* `false` means nothing remains that the environment's settings would let them in with (no
+* password where passwords are on, no verified address where the emailed code is on, no
+* connected provider that is enabled): the operator has to give the account a way in, for
+* example the user's own "Forgot password" where the password method is on. The route still
+* answers `204` with no body; the header is how the outcome is told without changing that.
+*
+* @example
+* ```ts
+* const res = await fetch(`${api}/v1/admin/users/${userId}/factors`, {
+*   method: 'DELETE',
+*   headers: { authorization: `Bearer ${secretKey}` },
+* })
+* const lockedOut = res.headers.get(CAN_STILL_SIGN_IN_HEADER) === 'false'
+* ```
+*/
+declare const CAN_STILL_SIGN_IN_HEADER = "x-tula-can-still-sign-in";
+/**
+* Request header of `PUT /v1/admin/settings` naming the tool that manages the environment's
+* settings from a config file (`tula-apply`), or `none` to hand them back.
+*
+* Sent together with {@link CONFIG_HASH_HEADER}. The API records both with the settings and
+* returns them as `managedBy`, so a dashboard can say "these settings come from a config file"
+* and warn when they were changed around it. A replace without the header keeps the record,
+* which then shows as drifted. See ADR 0030.
+*
+* @example
+* ```ts
+* headers[CONFIG_MANAGED_BY_HEADER] = 'tula-apply'
+* headers[CONFIG_HASH_HEADER] = await hashEnvironmentConfig(environment)
+* ```
+*/
+declare const CONFIG_MANAGED_BY_HEADER = "x-tula-managed-by";
+/**
+* Request header of `PUT /v1/admin/settings` carrying the fingerprint of the config file's
+* content for the environment: `sha256:` and 64 hex characters. It identifies a version of the
+* file; it is computed over secret **names**, never values.
+*
+* @example
+* ```ts
+* headers[CONFIG_HASH_HEADER] // 'sha256:9f2c…'
+* ```
+*/
+declare const CONFIG_HASH_HEADER = "x-tula-config-hash";
+/**
+* The value of {@link CONFIG_MANAGED_BY_HEADER} that removes the record of a managing tool.
+*
+* @example
+* ```ts
+* headers[CONFIG_MANAGED_BY_HEADER] = CONFIG_UNMANAGED
+* ```
+*/
+declare const CONFIG_UNMANAGED = "none";
+/**
+* Request header every call the dashboard makes with its session cookie must carry, with the
+* value {@link DASHBOARD_HEADER_VALUE} (ADR 0032).
+*
+* A browser attaches a cookie whoever wrote the page. This header is what a form cannot send
+* and what a cross-origin `fetch` may send only after a preflight, which the API answers for
+* the deployment's own origins alone. Without it the dashboard session cookie is ignored. With
+* it, an `Authorization` header is refused: one request has one credential.
+*
+* @example
+* ```ts
+* await fetch('/v1/instance/session', { headers: { [DASHBOARD_HEADER]: DASHBOARD_HEADER_VALUE } })
+* ```
+*/
+declare const DASHBOARD_HEADER = "x-tula-dashboard";
+/**
+* The one value of {@link DASHBOARD_HEADER} the API accepts.
+*
+* @example
+* ```ts
+* headers[DASHBOARD_HEADER] = DASHBOARD_HEADER_VALUE
+* ```
+*/
+declare const DASHBOARD_HEADER_VALUE = "1";
+/**
+* Request header naming the environment an `/v1/admin/*` call made with a dashboard session is
+* for: the environment's id (a UUID). A secret key names its environment by itself and must not
+* send it.
+*
+* @example
+* ```ts
+* await fetch('/v1/admin/users', {
+*   headers: { [DASHBOARD_HEADER]: DASHBOARD_HEADER_VALUE, [ENVIRONMENT_HEADER]: environment.id },
+* })
+* ```
+*/
+declare const ENVIRONMENT_HEADER = "x-tula-environment";
+/**
+* Name of the dashboard session cookie (`HttpOnly`, `SameSite=Strict`). Over https it carries
+* the `__Secure-` prefix. A page never reads it; the name is published for operators and
+* proxies.
+*
+* @example
+* ```ts
+* const name = `${secure ? '__Secure-' : ''}${DASHBOARD_SESSION_COOKIE}`
+* ```
+*/
+declare const DASHBOARD_SESSION_COOKIE = "tula_dashboard";
+/**
+* Name of the URL-fragment parameter carrying an emailed sign-in link's token.
+*
+* The link is the app's own URL followed by `#tula_link=<token>&tula_attempt=<attempt id>`. A
+* fragment is never sent to a server, a proxy or in `Referer`, so the token reaches only the
+* page's own script, which posts it to `/v1/client/sign-ins/link` and removes it from the URL.
+*
+* @example
+* ```ts
+* const token = new URLSearchParams(location.hash.slice(1)).get(EMAIL_LINK_TOKEN_PARAM)
+* ```
+*/
+declare const EMAIL_LINK_TOKEN_PARAM = "tula_link";
+/**
+* Name of the URL-fragment parameter carrying the id of the sign-in an emailed link belongs to.
+*
+* @example
+* ```ts
+* const attemptId = new URLSearchParams(location.hash.slice(1)).get(EMAIL_LINK_ATTEMPT_PARAM)
+* ```
+*/
+declare const EMAIL_LINK_ATTEMPT_PARAM = "tula_attempt";
+/**
+* Name of the URL-fragment parameter carrying the single-use ticket an OAuth sign-in returns to
+* the app's page with (ADR 0026).
+*
+* The API redirects to the app's URL followed by `#tula_ticket=<ticket>&tula_attempt=<attempt
+* id>`. The page's script removes the fragment from the address and posts the ticket, with the
+* binding its browser kept, to `/v1/client/sign-ins/oauth/exchange`. The ticket is not a token:
+* it lasts a minute, works once, and only together with that binding.
+*
+* @example
+* ```ts
+* const ticket = new URLSearchParams(location.hash.slice(1)).get(OAUTH_TICKET_PARAM)
+* ```
+*/
+declare const OAUTH_TICKET_PARAM = "tula_ticket";
+/**
+* Name of the URL-fragment parameter carrying the contract error code of an OAuth sign-in that
+* failed before a ticket was issued (the user cancelled, the provider failed).
+*
+* @example
+* ```ts
+* const code = new URLSearchParams(location.hash.slice(1)).get(OAUTH_ERROR_PARAM)
+* ```
+*/
+declare const OAUTH_ERROR_PARAM = "tula_error";
+export { CAN_STILL_SIGN_IN_HEADER, CLIENT_HEADER, CONFIG_HASH_HEADER, CONFIG_MANAGED_BY_HEADER, CONFIG_UNMANAGED, DASHBOARD_HEADER, DASHBOARD_HEADER_VALUE, DASHBOARD_SESSION_COOKIE, EMAIL_LINK_ATTEMPT_PARAM, EMAIL_LINK_TOKEN_PARAM, ENVIRONMENT_HEADER, FLOW_ATTEMPT_HEADER, OAUTH_ERROR_PARAM, OAUTH_TICKET_PARAM, PUBLISHABLE_KEY_HEADER, SESSION_PROFILE_HEADER };

package/dist/headers.js

@@ -0,0 +1,36 @@
+import {
+  PUBLISHABLE_KEY_HEADER2,
+  CLIENT_HEADER2,
+  SESSION_PROFILE_HEADER2,
+  FLOW_ATTEMPT_HEADER2,
+  CAN_STILL_SIGN_IN_HEADER2,
+  CONFIG_MANAGED_BY_HEADER2,
+  CONFIG_HASH_HEADER2,
+  CONFIG_UNMANAGED2,
+  DASHBOARD_HEADER2,
+  DASHBOARD_HEADER_VALUE2,
+  ENVIRONMENT_HEADER2,
+  DASHBOARD_SESSION_COOKIE2,
+  EMAIL_LINK_TOKEN_PARAM2,
+  EMAIL_LINK_ATTEMPT_PARAM2,
+  OAUTH_TICKET_PARAM2,
+  OAUTH_ERROR_PARAM2
+} from "./shared/chunk-q309e9bk.js";
+export {
+  CAN_STILL_SIGN_IN_HEADER2 as CAN_STILL_SIGN_IN_HEADER,
+  CLIENT_HEADER2 as CLIENT_HEADER,
+  CONFIG_HASH_HEADER2 as CONFIG_HASH_HEADER,
+  CONFIG_MANAGED_BY_HEADER2 as CONFIG_MANAGED_BY_HEADER,
+  CONFIG_UNMANAGED2 as CONFIG_UNMANAGED,
+  DASHBOARD_HEADER2 as DASHBOARD_HEADER,
+  DASHBOARD_HEADER_VALUE2 as DASHBOARD_HEADER_VALUE,
+  DASHBOARD_SESSION_COOKIE2 as DASHBOARD_SESSION_COOKIE,
+  EMAIL_LINK_ATTEMPT_PARAM2 as EMAIL_LINK_ATTEMPT_PARAM,
+  EMAIL_LINK_TOKEN_PARAM2 as EMAIL_LINK_TOKEN_PARAM,
+  ENVIRONMENT_HEADER2 as ENVIRONMENT_HEADER,
+  FLOW_ATTEMPT_HEADER2 as FLOW_ATTEMPT_HEADER,
+  OAUTH_ERROR_PARAM2 as OAUTH_ERROR_PARAM,
+  OAUTH_TICKET_PARAM2 as OAUTH_TICKET_PARAM,
+  PUBLISHABLE_KEY_HEADER2 as PUBLISHABLE_KEY_HEADER,
+  SESSION_PROFILE_HEADER2 as SESSION_PROFILE_HEADER
+};