@kusinta/iot-schema 0.2.0-beta.6 → 0.2.0-beta.60

package/src/kusinta/iot/accountlink/v1/account_link_pb.d.ts

@@ -0,0 +1,591 @@
+// @generated by protoc-gen-es v2.12.0 with parameter "target=js+dts,import_extension=js"
+// @generated from file kusinta/iot/accountlink/v1/account_link.proto (package kusinta.iot.accountlink.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenEnum, GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { Message } from "@bufbuild/protobuf";
+import type { Duration, Timestamp } from "@bufbuild/protobuf/wkt";
+
+/**
+ * Describes the file kusinta/iot/accountlink/v1/account_link.proto.
+ */
+export declare const file_kusinta_iot_accountlink_v1_account_link: GenFile;
+
+/**
+ * A home's link at one service, as its residents see it: never its tokens or the account's
+ * name.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.AccountLink
+ */
+export declare type AccountLink = Message<"kusinta.iot.accountlink.v1.AccountLink"> & {
+  /**
+   * @generated from field: kusinta.iot.accountlink.v1.LinkedService service = 1;
+   */
+  service: LinkedService;
+
+  /**
+   * @generated from field: kusinta.iot.accountlink.v1.AccountLinkStatus status = 2;
+   */
+  status: AccountLinkStatus;
+
+  /**
+   * @generated from field: google.protobuf.Timestamp linked_since = 3;
+   */
+  linkedSince?: Timestamp | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.AccountLink.
+ * Use `create(AccountLinkSchema)` to create a new message.
+ */
+export declare const AccountLinkSchema: GenMessage<AccountLink>;
+
+/**
+ * A home's links, in reply to ListAccountLinks. A service with no link is not listed.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.AccountLinks
+ */
+export declare type AccountLinks = Message<"kusinta.iot.accountlink.v1.AccountLinks"> & {
+  /**
+   * @generated from field: repeated kusinta.iot.accountlink.v1.AccountLink links = 1;
+   */
+  links: AccountLink[];
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.AccountLinks.
+ * Use `create(AccountLinksSchema)` to create a new message.
+ */
+export declare const AccountLinksSchema: GenMessage<AccountLinks>;
+
+/**
+ * A single-use nonce for one home's link, in reply to RequestAccountLinkNonce: a compact JWS
+ * carrying AccountLinkNonceClaims, signed by the gateway. It passes between the gateway, the
+ * app and the api-server only; the service sees its hash (see the file comment). It names no
+ * home: the gateway records which home each jti was issued for.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.AccountLinkNonce
+ */
+export declare type AccountLinkNonce = Message<"kusinta.iot.accountlink.v1.AccountLinkNonce"> & {
+  /**
+   * @generated from field: string nonce = 1;
+   */
+  nonce: string;
+
+  /**
+   * As the claims' exp.
+   *
+   * @generated from field: google.protobuf.Timestamp expires_at = 2;
+   */
+  expiresAt?: Timestamp | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.AccountLinkNonce.
+ * Use `create(AccountLinkNonceSchema)` to create a new message.
+ */
+export declare const AccountLinkNonceSchema: GenMessage<AccountLinkNonce>;
+
+/**
+ * The contract for the claims of AccountLinkNonce.nonce, shared by the gateway, which signs
+ * it, and the api-server, which verifies it. NOT sent on the wire, like
+ * webrtc.v1.AppTokenClaims: registered claims are flat JWT strings and NumericDates.
+ *
+ * Signed with the private key of the gateway's client certificate — the one it connects to
+ * the api-server with, a P-256 key — as ES256. The JWS header carries "x5t#S256", the
+ * thumbprint of that certificate, so the api-server finds it across a renewal. A verifier
+ * MUST refuse any other "alg".
+ *
+ * Before it calls the service, the api-server MUST verify that the gateway named by iss is
+ * registered and neither deleted nor wiped, that the certificate the thumbprint names is its
+ * current certificate — or the one it replaced, for no more than 10 minutes after the
+ * renewal — and the signature by it, aud, svc and exp, and that sub is the user posting the
+ * code. When the grant comes back, the gateway MUST verify the signature by its own key —
+ * its current one, or the one it replaced for no more than 10 minutes after the renewal —
+ * that iss is itself, aud and exp, and then accept the nonce once, by its jti, for the home
+ * it recorded for that jti, and only while that user is still a household admin of the
+ * home. Both sides allow at most 60 seconds of clock skew on exp. A gateway that restarts
+ * mid-link may have lost its jti record and answer REJECTED; the household links again.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.AccountLinkNonceClaims
+ */
+export declare type AccountLinkNonceClaims = Message<"kusinta.iot.accountlink.v1.AccountLinkNonceClaims"> & {
+  /**
+   * The gateway's id (identity.v1.GatewayId value).
+   *
+   * @generated from field: string iss = 1;
+   */
+  iss: string;
+
+  /**
+   * Always "account-link".
+   *
+   * @generated from field: string aud = 2;
+   */
+  aud: string;
+
+  /**
+   * The user it was issued to (identity.v1.UserId value).
+   *
+   * @generated from field: string sub = 3;
+   */
+  sub: string;
+
+  /**
+   * @generated from field: google.protobuf.Timestamp iat = 4;
+   */
+  iat?: Timestamp | undefined;
+
+  /**
+   * No more than 10 minutes after iat.
+   *
+   * @generated from field: google.protobuf.Timestamp exp = 5;
+   */
+  exp?: Timestamp | undefined;
+
+  /**
+   * Unique among the gateway's nonces, and not guessable.
+   *
+   * @generated from field: string jti = 6;
+   */
+  jti: string;
+
+  /**
+   * The service, by its claim value (see LinkedService).
+   *
+   * @generated from field: string svc = 8;
+   */
+  svc: string;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.AccountLinkNonceClaims.
+ * Use `create(AccountLinkNonceClaimsSchema)` to create a new message.
+ */
+export declare const AccountLinkNonceClaimsSchema: GenMessage<AccountLinkNonceClaims>;
+
+/**
+ * An access token and what it allows: all a reader of the service needs, without the means
+ * to renew it.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.AccessGrant
+ */
+export declare type AccessGrant = Message<"kusinta.iot.accountlink.v1.AccessGrant"> & {
+  /**
+   * @generated from field: string access_token = 1;
+   */
+  accessToken: string;
+
+  /**
+   * @generated from field: google.protobuf.Timestamp expires_at = 2;
+   */
+  expiresAt?: Timestamp | undefined;
+
+  /**
+   * As granted, space-separated.
+   *
+   * @generated from field: string scope = 3;
+   */
+  scope: string;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.AccessGrant.
+ * Use `create(AccessGrantSchema)` to create a new message.
+ */
+export declare const AccessGrantSchema: GenMessage<AccessGrant>;
+
+/**
+ * A grant with its refresh token, which stays on the gateway.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.TokenGrant
+ */
+export declare type TokenGrant = Message<"kusinta.iot.accountlink.v1.TokenGrant"> & {
+  /**
+   * @generated from field: kusinta.iot.accountlink.v1.AccessGrant access = 1;
+   */
+  access?: AccessGrant | undefined;
+
+  /**
+   * @generated from field: string refresh_token = 2;
+   */
+  refreshToken: string;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.TokenGrant.
+ * Use `create(TokenGrantSchema)` to create a new message.
+ */
+export declare const TokenGrantSchema: GenMessage<TokenGrant>;
+
+/**
+ * A home's account linked, api-server → gateway. Answered with an AccountLinkResult carrying
+ * the same request_id. With no answer within 30 seconds, the api-server sends an
+ * AccountLinkCancelled, revokes the grant, and tells the app the link failed.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.AccountLinked
+ */
+export declare type AccountLinked = Message<"kusinta.iot.accountlink.v1.AccountLinked"> & {
+  /**
+   * Minted by the api-server, opaque, unique among its links in flight.
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * The nonce exactly as the app passed it as the OAuth state.
+   *
+   * @generated from field: string nonce = 2;
+   */
+  nonce: string;
+
+  /**
+   * @generated from field: kusinta.iot.accountlink.v1.TokenGrant grant = 3;
+   */
+  grant?: TokenGrant | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.AccountLinked.
+ * Use `create(AccountLinkedSchema)` to create a new message.
+ */
+export declare const AccountLinkedSchema: GenMessage<AccountLinked>;
+
+/**
+ * The api-server gave up waiting for an AccountLinkResult, api-server → gateway. A gateway
+ * that stored the grant for that request_id deletes it, and answers nothing.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.AccountLinkCancelled
+ */
+export declare type AccountLinkCancelled = Message<"kusinta.iot.accountlink.v1.AccountLinkCancelled"> & {
+  /**
+   * As AccountLinked.request_id.
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.AccountLinkCancelled.
+ * Use `create(AccountLinkCancelledSchema)` to create a new message.
+ */
+export declare const AccountLinkCancelledSchema: GenMessage<AccountLinkCancelled>;
+
+/**
+ * @generated from message kusinta.iot.accountlink.v1.AccountLinkResult
+ */
+export declare type AccountLinkResult = Message<"kusinta.iot.accountlink.v1.AccountLinkResult"> & {
+  /**
+   * As AccountLinked.request_id.
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * @generated from field: kusinta.iot.accountlink.v1.AccountLinkOutcome outcome = 2;
+   */
+  outcome: AccountLinkOutcome;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.AccountLinkResult.
+ * Use `create(AccountLinkResultSchema)` to create a new message.
+ */
+export declare const AccountLinkResultSchema: GenMessage<AccountLinkResult>;
+
+/**
+ * Asks the api-server to refresh a grant, gateway → api-server. Answered with a TokenRefreshed
+ * carrying the same request_id.
+ *
+ * The gateway refreshes only when it needs a current access token for a read — for a read
+ * by a connector, while a connector session reading through the link is open — and not
+ * before the access token is near its expiry, with a random margin, so that gateways do not
+ * refresh together; and it has at most one refresh of a grant in flight. A gateway with no
+ * answer asks again with the same request_id and refresh token, for up to 10 minutes; after
+ * that it sends the old token no more, and the household links again.
+ *
+ * The api-server MUST keep its answer, keyed by the requesting gateway's identity and a hash
+ * of the refresh token, for 10 minutes, and answer a repeated request from it without asking
+ * the service: a service may rotate the refresh token, and a second exchange of the old one
+ * would end the link. It is held in the memory of the process that answered — the one
+ * holding the gateway's stream — and never shared, persisted or logged; it goes at the end of
+ * the 10 minutes or of the process. A restart, or the stream moving to another process,
+ * within them loses it, and a retry then exchanges the old token again: where the service
+ * rotates refresh tokens the link ends and the household links again. That is accepted.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.RefreshToken
+ */
+export declare type RefreshToken = Message<"kusinta.iot.accountlink.v1.RefreshToken"> & {
+  /**
+   * Minted by the gateway, opaque, unique among its requests in flight.
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * @generated from field: kusinta.iot.accountlink.v1.LinkedService service = 2;
+   */
+  service: LinkedService;
+
+  /**
+   * @generated from field: string refresh_token = 3;
+   */
+  refreshToken: string;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.RefreshToken.
+ * Use `create(RefreshTokenSchema)` to create a new message.
+ */
+export declare const RefreshTokenSchema: GenMessage<RefreshToken>;
+
+/**
+ * @generated from message kusinta.iot.accountlink.v1.TokenRefreshed
+ */
+export declare type TokenRefreshed = Message<"kusinta.iot.accountlink.v1.TokenRefreshed"> & {
+  /**
+   * As RefreshToken.request_id.
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * OK: grant replaces the gateway's. REJECTED: the service refused the refresh token, the
+   * link is gone, and the household links again. UNAVAILABLE: ask again after retry_after.
+   *
+   * @generated from field: kusinta.iot.accountlink.v1.TokenOutcome outcome = 2;
+   */
+  outcome: TokenOutcome;
+
+  /**
+   * OK only, and always whole: where the service issued no new refresh token, the api-server
+   * fills in the one it was sent.
+   *
+   * @generated from field: kusinta.iot.accountlink.v1.TokenGrant grant = 3;
+   */
+  grant?: TokenGrant | undefined;
+
+  /**
+   * See TokenOutcome.
+   *
+   * @generated from field: google.protobuf.Duration retry_after = 4;
+   */
+  retryAfter?: Duration | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.TokenRefreshed.
+ * Use `create(TokenRefreshedSchema)` to create a new message.
+ */
+export declare const TokenRefreshedSchema: GenMessage<TokenRefreshed>;
+
+/**
+ * Asks the api-server to revoke a grant, gateway → api-server: when a household unlinks or
+ * hands its home over, or a link is replaced. Answered with a TokenRevoked carrying the same
+ * request_id.
+ *
+ * The gateway reads no more through the grant once it asks. It keeps only the refresh token,
+ * and only to ask again: after retry_after on UNAVAILABLE, until OK or REJECTED, and for no
+ * more than 7 days. That pending revocation is stored encrypted, so it survives a restart,
+ * and it outlives a household handover's wipe and a gateway-wide wipe, which delete the
+ * grant itself: it is the only means left of ending the link at the service.
+ *
+ * A service with no means of revoking a grant is answered REJECTED by the api-server without
+ * asking the service. The gateway drops the token as for any REJECTED, and the grant stays
+ * valid at the service until it expires or the account holder removes the access there. So an
+ * app never tells the household that the service revoked the access, only that the home no
+ * longer holds it; where the service has no revocation, it may say that the access is removed
+ * at the service by the account holder.
+ *
+ * @generated from message kusinta.iot.accountlink.v1.RevokeToken
+ */
+export declare type RevokeToken = Message<"kusinta.iot.accountlink.v1.RevokeToken"> & {
+  /**
+   * Minted by the gateway, opaque, unique among its requests in flight.
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * @generated from field: kusinta.iot.accountlink.v1.LinkedService service = 2;
+   */
+  service: LinkedService;
+
+  /**
+   * @generated from field: string refresh_token = 3;
+   */
+  refreshToken: string;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.RevokeToken.
+ * Use `create(RevokeTokenSchema)` to create a new message.
+ */
+export declare const RevokeTokenSchema: GenMessage<RevokeToken>;
+
+/**
+ * @generated from message kusinta.iot.accountlink.v1.TokenRevoked
+ */
+export declare type TokenRevoked = Message<"kusinta.iot.accountlink.v1.TokenRevoked"> & {
+  /**
+   * As RevokeToken.request_id.
+   *
+   * @generated from field: string request_id = 1;
+   */
+  requestId: string;
+
+  /**
+   * OK: revoked. REJECTED: the service no longer knew the token, which is as good — or it has
+   * no means of revoking one, which the api-server answers without asking it (RevokeToken);
+   * either way the gateway drops the token. UNAVAILABLE: ask again after retry_after.
+   *
+   * @generated from field: kusinta.iot.accountlink.v1.TokenOutcome outcome = 2;
+   */
+  outcome: TokenOutcome;
+
+  /**
+   * See TokenOutcome.
+   *
+   * @generated from field: google.protobuf.Duration retry_after = 3;
+   */
+  retryAfter?: Duration | undefined;
+};
+
+/**
+ * Describes the message kusinta.iot.accountlink.v1.TokenRevoked.
+ * Use `create(TokenRevokedSchema)` to create a new message.
+ */
+export declare const TokenRevokedSchema: GenMessage<TokenRevoked>;
+
+/**
+ * @generated from enum kusinta.iot.accountlink.v1.AccountLinkStatus
+ */
+export enum AccountLinkStatus {
+  /**
+   * @generated from enum value: ACCOUNT_LINK_STATUS_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * @generated from enum value: ACCOUNT_LINK_STATUS_LINKED = 1;
+   */
+  LINKED = 1,
+
+  /**
+   * A refresh was REJECTED, or went unanswered past its retry window: the household links
+   * again.
+   *
+   * @generated from enum value: ACCOUNT_LINK_STATUS_NEEDS_RELINK = 2;
+   */
+  NEEDS_RELINK = 2,
+}
+
+/**
+ * Describes the enum kusinta.iot.accountlink.v1.AccountLinkStatus.
+ */
+export declare const AccountLinkStatusSchema: GenEnum<AccountLinkStatus>;
+
+/**
+ * The services a home's account can be linked at. Each value names the fixed string that
+ * stands for it in a nonce's "svc" claim, which never changes with the value's name.
+ *
+ * @generated from enum kusinta.iot.accountlink.v1.LinkedService
+ */
+export enum LinkedService {
+  /**
+   * @generated from enum value: LINKED_SERVICE_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * NIBE's myUplink. Claim value "myuplink".
+   *
+   * @generated from enum value: LINKED_SERVICE_MYUPLINK = 1;
+   */
+  MYUPLINK = 1,
+}
+
+/**
+ * Describes the enum kusinta.iot.accountlink.v1.LinkedService.
+ */
+export declare const LinkedServiceSchema: GenEnum<LinkedService>;
+
+/**
+ * @generated from enum kusinta.iot.accountlink.v1.AccountLinkOutcome
+ */
+export enum AccountLinkOutcome {
+  /**
+   * Sender did not set an outcome, or sent one this schema does not know: read as REJECTED.
+   *
+   * @generated from enum value: ACCOUNT_LINK_OUTCOME_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * Stored. A link the home already had at the same service is replaced. The gateway keeps
+   * the replaced grant, unused, and revokes it (RevokeToken) only once 60 seconds have passed
+   * since this answer with no AccountLinkCancelled for its request_id; on a cancel within
+   * them, it deletes the new grant and restores the replaced one.
+   *
+   * @generated from enum value: ACCOUNT_LINK_OUTCOME_LINKED = 1;
+   */
+  LINKED = 1,
+
+  /**
+   * The nonce failed the gateway's checks (AccountLinkNonceClaims). Nothing is stored, and
+   * the api-server revokes the grant.
+   *
+   * @generated from enum value: ACCOUNT_LINK_OUTCOME_REJECTED = 2;
+   */
+  REJECTED = 2,
+}
+
+/**
+ * Describes the enum kusinta.iot.accountlink.v1.AccountLinkOutcome.
+ */
+export declare const AccountLinkOutcomeSchema: GenEnum<AccountLinkOutcome>;
+
+/**
+ * On UNAVAILABLE the api-server sets retry_after: the service's own wait where it gave one,
+ * spread across the gateways asking. A gateway waits at least retry_after and at least 30
+ * seconds, unset reading as 30, and doubles its wait on each further UNAVAILABLE for the
+ * same token, up to an hour, with a random margin.
+ *
+ * @generated from enum kusinta.iot.accountlink.v1.TokenOutcome
+ */
+export enum TokenOutcome {
+  /**
+   * Sender did not set an outcome, or sent one this schema does not know: read as
+   * UNAVAILABLE.
+   *
+   * @generated from enum value: TOKEN_OUTCOME_UNSPECIFIED = 0;
+   */
+  UNSPECIFIED = 0,
+
+  /**
+   * @generated from enum value: TOKEN_OUTCOME_OK = 1;
+   */
+  OK = 1,
+
+  /**
+   * @generated from enum value: TOKEN_OUTCOME_REJECTED = 2;
+   */
+  REJECTED = 2,
+
+  /**
+   * @generated from enum value: TOKEN_OUTCOME_UNAVAILABLE = 3;
+   */
+  UNAVAILABLE = 3,
+}
+
+/**
+ * Describes the enum kusinta.iot.accountlink.v1.TokenOutcome.
+ */
+export declare const TokenOutcomeSchema: GenEnum<TokenOutcome>;
+