mesh-controller/internal/licences/migrations/0001-a-licence-is-a-named-thing.sql

-- A licence is a named thing, and the name is the operator's.
--
-- novox/hq ADR 0024. Not an anonymous credential hanging off a vendor: *the personal account*,
-- *the organisation's account* are names a person uses, and the mesh has to use them too, because
-- the whole point is saying WHICH ONE a given consumer uses.
--
-- **Many to many.** One vendor has several licences; one licence serves several consumers. So it
-- is deliberately not a claim — claims are for things only one holder may have, and two machines
-- sharing an account is the ordinary case rather than a collision.

create table licence (
    -- The operator's name for it. The primary key, because that is what a person types and what a
    -- consumer is pinned to.
    name     text        primary key,
    -- Which company sells it: anthropic, openai, a model the mesh runs itself. Selects the adapter
    -- that runs this licence's lifecycle (novox/hq ADR 0050). Named `vendor`, not `provider`: the
    -- inventory already uses "provider" for which node answers a brokered provision.
    vendor   text        not null,
    -- What a consumer needs to know that is not secret -- a base URL, a model name. The key is
    -- never here.
    serves   jsonb       not null default '{}'::jsonb,
    -- The one node that holds this licence's refresh token readably, and refreshes it (novox/hq
    -- ADR 0050's carve-out). Null for a static-key licence, which has nothing to refresh and no
    -- manager -- and the null is the check that a static key never grows a readable-at-rest value.
    -- A name, not a foreign key: nodes live in another context this one may not join across
    -- (novox/hq ADR 0008).
    manager  text,
    added_at timestamptz not null default now()
);

-- Who holds it, and the key sealed to them.
--
-- **The node is a name, not a foreign key.** It lives in another context and this one may not join
-- across that boundary (novox/hq ADR 0008); a name is the published identifier and is what
-- crossing a context boundary is allowed to carry.
create table licence_holder (
    licence text not null references licence(name) on delete cascade,
    node    text not null,
    module  text not null,

    -- Sealed to that node's key. Null until a key has been supplied while this holder existed --
    -- which is a real state and not an error: the mesh discarded the plaintext, so it cannot seal
    -- to a holder that arrived afterwards, and saying so is better than delivering nothing.
    sealed   text,
    node_key text,

    added_at timestamptz not null default now(),
    primary key (licence, node, module)
);

-- The refresh token, encrypted at rest under the manager node's key.
--
-- **novox/hq ADR 0050's carve-out, and its one home.** A `refreshable-grant` licence cannot be both
-- sealed so the mesh cannot read it and rotated centrally, because rotating means a node reads the
-- refresh token back. So exactly one node -- the licence's manager -- holds it readably, and it is
-- kept here as an envelope only that node can open: a symmetric data key encrypts the token
-- (secretbox), and the data key is sealed to the manager's public key. This database on its own
-- holds ciphertext and a wrapped key with no private half to open either (novox/hq ADR 0004).
--
-- **Separate from the access tokens.** licence_holder.sealed is the ACCESS token, sealed per holder
-- and delivered. This is the REFRESH token, one per licence, never delivered to anybody. Keeping
-- them in different tables is what makes "the refresh token is stripped on delivery" structural:
-- delivery reads licence_holder, and the refresh token is not in it.
create table refresh_grant (
    -- One refresh token per licence. On delete cascade: forgetting a licence forgets its refresh
    -- token with it, the same way it forgets its holders.
    licence     text primary key references licence(name) on delete cascade,

    -- base64( nonce || secretbox(data_key, refresh_token) ) -- the token under the symmetric key.
    token       text not null,
    -- base64( anonymous-box(manager_key, data_key) ) -- the data key closed to the manager node.
    wrapped_key text not null,
    -- The manager's public sealing key the data key was wrapped to. Kept so a manager that
    -- regenerated its key can be told it can no longer open this, rather than discovering it as a
    -- refresh that will not decrypt (the same reason licence_holder.node_key is kept).
    manager_key text not null,

    updated_at  timestamptz not null default now()
);