claim

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package claim holds the logic shared by the claim-initiate and claim-verify Lambdas: the configured variant, MAC normalization, claim-key construction, and the per-caller quota.

The variant and the quota are read at runtime from the claiming configuration document in SSM (ca_bootstrap.ParamConfig), set through the admin config API — not from deploy-time inputs. Deploying the claim stack group stands up the infrastructure; the configuration (plus a minted CA) is what turns claiming on. A configuration with no variant reads as off, and the handlers fail closed.

A claim vends a certificate and assigns a node ID. It confers no permission over the node. Device control comes from the primary user-node mapping, established separately by challenge-response — a proof of physical possession. The reservation is therefore not an authorization record: it exists to make node IDs stable and idempotent, to bound how many a caller can mint, and to stop one caller's claim from disturbing another's device. Anything later scoped to a node's owner must key on the primary mapping, never on this table.

The claim key is what carries that last property. It decides which reservation — and therefore which node ID — a request resolves to, and its shape differs by variant:

  • The variant that cannot prove possession (user_authenticated) keys on {mac_addr, caller}. Without the caller dimension, one caller claiming another caller's MAC would resolve to the same node ID and replace the certificate on a device already in service — an unauthenticated denial of service against someone else's hardware.
  • The variant that can prove possession (device_attested) keys on mac_addr alone. The caller dimension would buy nothing there and would cost correctness: a device changing hands should keep one identity, not accumulate an orphaned node per previous owner.

See docs/en/specs/assisted-claiming.md.

Index

Constants

View Source
const (
	TagKeyRegisteredFrom = "registered_from"
	TagKeyCreatedBy      = "created_by"
	TagKeyRegisteredAt   = "registered_at"
)

Provenance tag keys. These reuse the keys the admin dashboard already registers as searchable fleet-index fields ("Registered From", "Created By"), so a claimed node is findable by exactly the same filters as one registered through the dashboard. Without them, claimed nodes would be the only nodes in the fleet absent from a `registered_from` search rather than merely untagged.

View Source
const DefaultMaxNodesPerClaimant = 20

DefaultMaxNodesPerClaimant bounds how many node IDs one caller can mint.

This is a lifetime cap, not a cap on nodes currently held: reservations are never deleted, so removing a node from an account does not return its slot. That is deliberate — a reclaimable quota would be no bound at all, since a caller could mint, release, and mint again without limit (requirements Req 14).

View Source
const NodeIDLength = 36

NodeIDLength is the fixed width of a claimed node ID: the 36 characters of a canonical RFC 4122 UUID (32 hex digits plus four hyphens).

Variables

View Source
var ErrUnknownVariant = fmt.Errorf("unknown claiming variant")

ErrUnknownVariant is returned when the configured variant is unrecognized. Callers map it to a 500: an unknown variant means a misconfigured deployment, never a bad request.

Functions

func GenerateNodeID

func GenerateNodeID() (string, error)

GenerateNodeID returns a cloud-assigned node ID: a canonical RFC 4122 version-4 UUID in the standard hyphenated lowercase form, e.g. "1b4e28ba-2fa1-4d3b-a3f5-ce6f8a9b0c2d".

This is the same format the DAC and RainMaker pre-provisioning services emit, so a node's ID reads identically whichever path minted it. One value serves as the IoT Thing name, the MQTT client ID and the certificate Common Name.

A claimed node that later joins a Matter fabric has its Matter operational Node ID derived from this value exactly as it is for every other node whose ID is not already 16 hex characters (group.MatterNodeIDFromThingName). The node ID is not itself a Matter Node ID — that identity is fabric-scoped and assigned during association, not at claim time.

func NormalizeMacAddr

func NormalizeMacAddr(macAddr string) (string, error)

NormalizeMacAddr strips separators, upper-cases, and validates that what remains is 12 or 16 hexadecimal characters.

Normalizing is not cosmetic. The MAC is what identifies a device in the reservation key, so "AA:BB:CC:DD:EE:FF", "aa-bb-cc-dd-ee-ff" and "AABBCCDDEEFF" must resolve to one reservation. Storing them verbatim would give the same physical device three node IDs, three certificates, and three quota slots, and would make the idempotence guarantee depend on a client's formatting convention rather than on the device (requirements Req 2.2, 2.3).

func ProvenanceTags

func ProvenanceTags(v Variant, callerID string) []string

ProvenanceTags returns the "key:value" tags to stamp on a claimed node.

These are set by the server and are deliberately not accepted from the request. The caller is an end user; letting them supply `registered_from` would let them label their node as having come from the dashboard, which is exactly the claim an administrator needs to be able to trust.

callerID is the authenticated user who drove the claim, which is not the same thing as the claim key's claimant. Under device_attested the key is the MAC alone — possession is proven, so a caller dimension in the *key* would be wrong — but a user may still have initiated the claim, and recording who did is worth having for support and audit. Passing the caller rather than the key means that tag appears there too, without the key ever gaining a user.

The sentinel is filtered defensively: it is not a user, and it must never surface in a column labelled "Created By".

func Quota

func Quota(ctx context.Context, v Variant) (int, bool)

Quota returns the per-caller reservation limit for the variant and whether a limit applies at all.

device_attested has no user quota, and could not have one: its claim key carries no caller, so there is nothing to count per user. It does not need one either — the device secrets service is the abuse control there, and a stronger one, since it bounds issuance to devices that were actually manufactured rather than to a number someone picked (Req 6.5, 14.4).

func RegisteredAtTag

func RegisteredAtTag(t time.Time) string

RegisteredAtTag records when a node first entered the fleet.

Nothing else exposes this to an administrator: reg_ts is written to the node row but the fleet index the console searches reads shadows, not DynamoDB, and iot:DescribeThing carries no creation date at all. As a tag it becomes visible and searchable alongside the other provenance.

RFC 3339 UTC so it sorts lexicographically in a fleet-index range query. The value contains colons, which is fine — tags split on the first one only.

func ValidateConfiguredMode

func ValidateConfiguredMode(mode string) error

ValidateConfiguredMode checks an operator-supplied mode before it is stored as the claiming configuration. An empty mode is allowed and means claiming is configured off. A non-empty mode must name a variant that is both recognized and implemented; anything else is rejected so a bad value fails at the config API rather than silently at claim time. This lives here, not in ca_bootstrap, because it needs the Variant type (and ca_bootstrap must not import claim).

Types

type Key

type Key struct {
	MacAddr string
	// ClaimantID is who the claim is recorded against: the authenticated
	// caller's internal user ID, or the device sentinel under
	// device_attested. It is not a tenant — this deployment model has no
	// tenancy concept.
	ClaimantID string
}

Key identifies the reservation a claim resolves to. Its fields map directly onto the reservation table's partition and sort keys.

func NewKey

func NewKey(v Variant, macAddr, callerID string) (Key, error)

NewKey builds the claim key for a variant.

callerID is the authenticated caller's resolved internal user ID; it is ignored for device_attested, which has no caller dimension.

type Variant

type Variant string

Variant is the claiming mode. Its string values are the ones accepted by the admin config API (validated via ValidateConfiguredMode) and stored as the configuration's Mode.

const (
	// VariantUserAuthenticated gates the claim on an authenticated caller.
	// This is the only variant that vends certificates to users, and it is
	// what any deployment enabling claiming gets.
	VariantUserAuthenticated Variant = "user_authenticated"
	// VariantDeviceAttested gates the claim on the device proving itself
	// against the secrets service, with no caller dimension.
	VariantDeviceAttested Variant = "device_attested"
)

func CurrentVariant

func CurrentVariant(ctx context.Context) Variant

CurrentVariant reads the configured variant from the claiming configuration document in SSM (cached — this is a hot per-request path). Returns "" when claiming is unconfigured or the configuration cannot be read, so a claim fails closed rather than proceeding on a stale or absent variant.

func (Variant) IsImplemented

func (v Variant) IsImplemented() bool

IsImplemented reports whether v is not merely recognized but actually built. A known-but-unimplemented variant (device_attested today) must never be accepted as configuration: its entitlement check does not exist yet, so vending under its name would be weaker than the name implies.

func (Variant) IsValid

func (v Variant) IsValid() bool

IsValid reports whether v names a variant this build understands.

func (Variant) RegisteredFrom

func (v Variant) RegisteredFrom() string

RegisteredFrom returns the provenance value recorded for this variant, or "" if the variant is unknown.

func (Variant) RequiresCaller

func (v Variant) RequiresCaller() bool

RequiresCaller reports whether the variant needs an authenticated caller. device_attested authenticates the device, not a user.

Directories

Path Synopsis
Package ca_bootstrap mints and publishes the assisted-claiming CA and holds the operator certificate configuration it mints from.
Package ca_bootstrap mints and publishes the assisted-claiming CA and holds the operator certificate configuration it mints from.
handlers
claim_admin command
Claim admin API: admin-only configuration and bootstrap of the claiming CA.
Claim admin API: admin-only configuration and bootstrap of the claiming CA.
claim_handler command
Claim handler lambda: POST /v1/claim/initiate and POST /v1/claim/verify.
Claim handler lambda: POST /v1/claim/initiate and POST /v1/claim/verify.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL