@portpowered/reference-data 0.0.0-stage → 0.4.0

package/generated/public/docs/references/capability-interfaces/security-pin/1.0/messages/query-pins.yaml

@@ -0,0 +1,15 @@
+description: >-
+  Query a bounded endpoint-scoped PIN record page. Requires message-send
+  permission. Continuations bind caller, endpoint and page size; return
+  pin-records-report with the request correlation token in its header.
+type: object
+properties:
+  maxResults:
+    type: integer
+    minimum: 1
+    maximum: 100
+    default: 20
+  nextToken:
+    type: string
+    minLength: 1
+additionalProperties: false

package/generated/public/docs/references/capability-interfaces/security-pin/1.0/messages/update-pin.yaml

@@ -0,0 +1,27 @@
+description: >-
+  Update an endpoint-scoped record. Require at least one change. Kind is
+  immutable; validity changes require both timestamps and an authoritative
+  TEMPORARY record.
+type: object
+properties:
+  id:
+    type: string
+    minLength: 1
+    description: Opaque record ID, resolved only within the authorized endpoint.
+  name:
+    type: string
+  pin:
+    type: string
+    writeOnly: true
+    description: >-
+      Credential preserved as a string. Redact from diagnostics and persisted
+      history.
+  validFrom:
+    type: string
+    format: date-time
+  validUntil:
+    type: string
+    format: date-time
+required:
+  - id
+additionalProperties: false

package/generated/public/docs/references/capability-interfaces/security-pin/1.0.yaml

@@ -0,0 +1,348 @@
+name: security-pin
+namespace: port1/systems/zero/capability-interfaces/security-pin
+version: '1.0'
+description: >-
+  Security PINs create, update, query, and delete PIN records. Follow operation results and PIN
+  reports when managing the records supported by a device.
+messages:
+  - name: create-pin
+    description: >-
+      Create an endpoint-scoped PIN. TEMPORARY requires both validity timestamps; PERMANENT forbids
+      them. Validate increasing, nonexpired instants and declared restrictions before dispatch.
+    directionality: in
+    schema:
+      description: >-
+        Create an endpoint-scoped PIN. TEMPORARY requires both validity timestamps; PERMANENT
+        forbids them. Validate increasing, nonexpired instants and declared restrictions before
+        dispatch.
+      type: object
+      properties:
+        name:
+          type: string
+        pin:
+          type: string
+          writeOnly: true
+          description: Credential preserved as a string. Redact from diagnostics and persisted history.
+        kind:
+          type: string
+          enum:
+            - PERMANENT
+            - TEMPORARY
+        validFrom:
+          type: string
+          format: date-time
+        validUntil:
+          type: string
+          format: date-time
+      required:
+        - name
+        - pin
+        - kind
+      additionalProperties: false
+  - name: delete-pin
+    description: >-
+      Delete a record within the authorized endpoint. Emit a correlated terminal result even when
+      enumeration no longer includes the record.
+    directionality: in
+    schema:
+      description: >-
+        Delete a record within the authorized endpoint. Emit a correlated terminal result even when
+        enumeration no longer includes the record.
+      type: object
+      properties:
+        id:
+          type: string
+          minLength: 1
+          description: Opaque record ID; never the PIN value.
+      required:
+        - id
+      additionalProperties: false
+  - name: pin-operation-result
+    description: >-
+      Correlated safe PIN provisioning result. APPLIED requires vendor-confirmed completion, not
+      dispatch acceptance. CREATE supplies recordId once assigned; UPDATE and DELETE retain the
+      requested ID. FAILED requires a safe code; other statuses forbid code. Never include
+      credentials or raw vendor errors.
+    directionality: out
+    schema:
+      description: >-
+        Correlated safe PIN provisioning result. APPLIED requires vendor-confirmed completion, not
+        dispatch acceptance. CREATE supplies recordId once assigned; UPDATE and DELETE retain the
+        requested ID. FAILED requires a safe code; other statuses forbid code. Never include
+        credentials or raw vendor errors.
+      type: object
+      properties:
+        correlationToken:
+          type: string
+          minLength: 1
+        operation:
+          type: string
+          enum:
+            - CREATE
+            - UPDATE
+            - DELETE
+        recordId:
+          type: string
+          minLength: 1
+        provisioningStatus:
+          type: string
+          enum:
+            - PENDING
+            - APPLIED
+            - FAILED
+        code:
+          type: string
+          minLength: 1
+          description: >-
+            Stable safe structured failure code. Never raw vendor text, credentials or response
+            bodies.
+      required:
+        - correlationToken
+        - operation
+        - provisioningStatus
+      additionalProperties: false
+  - name: pin-records-report
+    description: >-
+      Bounded credential-free record page aligned with the pin-records attribute. Echo the query
+      correlation token in the message header.
+    directionality: out
+    schema:
+      description: >-
+        Bounded credential-free record page aligned with the pin-records attribute. Echo the query
+        correlation token in the message header.
+      type: object
+      properties:
+        items:
+          type: array
+          maxItems: 100
+          items:
+            description: >-
+              Endpoint-scoped PIN metadata without credentials. TEMPORARY requires both validity
+              timestamps; PERMANENT forbids them. Provisioning status is distinct from observation
+              freshness.
+            type: object
+            properties:
+              id:
+                type: string
+                minLength: 1
+              name:
+                type: string
+              kind:
+                type: string
+                enum:
+                  - PERMANENT
+                  - TEMPORARY
+              validFrom:
+                type: string
+                format: date-time
+              validUntil:
+                type: string
+                format: date-time
+              provisioningStatus:
+                type: string
+                enum:
+                  - PENDING
+                  - APPLIED
+                  - FAILED
+            required:
+              - id
+              - name
+              - kind
+              - provisioningStatus
+            additionalProperties: false
+            title: SecurityPinRecord
+        nextToken:
+          type: string
+          minLength: 1
+          description: Opaque continuation bound to endpoint, caller and query; omitted on the final page.
+      required:
+        - items
+      additionalProperties: false
+  - name: query-operation
+    description: >-
+      Retrieve an endpoint-scoped PIN operation result by its original correlation token. Enforce
+      caller and endpoint ownership. Return pin-operation-result, preserving the original operation
+      correlation token in its payload and using this query's correlation token in the response
+      header.
+    directionality: in
+    schema:
+      description: >-
+        Retrieve an endpoint-scoped PIN operation result by its original correlation token. Enforce
+        caller and endpoint ownership. Return pin-operation-result, preserving the original
+        operation correlation token in its payload and using this query's correlation token in the
+        response header.
+      type: object
+      properties:
+        correlationToken:
+          type: string
+          minLength: 1
+      required:
+        - correlationToken
+      additionalProperties: false
+  - name: query-pins
+    description: >-
+      Query a bounded endpoint-scoped PIN record page. Requires message-send permission.
+      Continuations bind caller, endpoint and page size; return pin-records-report with the request
+      correlation token in its header.
+    directionality: in
+    schema:
+      description: >-
+        Query a bounded endpoint-scoped PIN record page. Requires message-send permission.
+        Continuations bind caller, endpoint and page size; return pin-records-report with the
+        request correlation token in its header.
+      type: object
+      properties:
+        maxResults:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+        nextToken:
+          type: string
+          minLength: 1
+      additionalProperties: false
+  - name: update-pin
+    description: >-
+      Update an endpoint-scoped record. Require at least one change. Kind is immutable; validity
+      changes require both timestamps and an authoritative TEMPORARY record.
+    directionality: in
+    schema:
+      description: >-
+        Update an endpoint-scoped record. Require at least one change. Kind is immutable; validity
+        changes require both timestamps and an authoritative TEMPORARY record.
+      type: object
+      properties:
+        id:
+          type: string
+          minLength: 1
+          description: Opaque record ID, resolved only within the authorized endpoint.
+        name:
+          type: string
+        pin:
+          type: string
+          writeOnly: true
+          description: Credential preserved as a string. Redact from diagnostics and persisted history.
+        validFrom:
+          type: string
+          format: date-time
+        validUntil:
+          type: string
+          format: date-time
+      required:
+        - id
+      additionalProperties: false
+attributes:
+  - name: pin-records
+    description: >-
+      Bounded endpoint-scoped PIN record page containing no credentials. Permanent records omit
+      validity bounds; temporary records include both. Provisioning status is separate from
+      observation freshness.
+    schema:
+      description: >-
+        Bounded endpoint-scoped PIN record page containing no credentials. Permanent records omit
+        validity bounds; temporary records include both. Provisioning status is separate from
+        observation freshness.
+      type: object
+      properties:
+        items:
+          type: array
+          maxItems: 100
+          items:
+            description: >-
+              Endpoint-scoped PIN metadata without credentials. TEMPORARY requires both validity
+              timestamps; PERMANENT forbids them. Provisioning status is distinct from observation
+              freshness.
+            type: object
+            properties:
+              id:
+                type: string
+                minLength: 1
+              name:
+                type: string
+              kind:
+                type: string
+                enum:
+                  - PERMANENT
+                  - TEMPORARY
+              validFrom:
+                type: string
+                format: date-time
+              validUntil:
+                type: string
+                format: date-time
+              provisioningStatus:
+                type: string
+                enum:
+                  - PENDING
+                  - APPLIED
+                  - FAILED
+            required:
+              - id
+              - name
+              - kind
+              - provisioningStatus
+            additionalProperties: false
+            title: SecurityPinRecord
+        nextToken:
+          type: string
+          minLength: 1
+          description: Opaque continuation bound to endpoint, caller and query; omitted on the final page.
+      required:
+        - items
+      additionalProperties: false
+  - name: pin-support
+    description: >-
+      Verified optional restrictions from endpoint configuration. Omit unknown restrictions; absence
+      does not guarantee vendor acceptance.
+    schema:
+      description: >-
+        Verified optional restrictions from endpoint configuration. Omit unknown restrictions;
+        absence does not guarantee vendor acceptance.
+      type: object
+      properties:
+        supportedKinds:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+            enum:
+              - PERMANENT
+              - TEMPORARY
+        minLength:
+          type: integer
+          minimum: 0
+        maxLength:
+          type: integer
+          minimum: 0
+        pattern:
+          type: string
+      additionalProperties: false
+configuration:
+  description: >-
+    Security PINs create, update, query, and delete PIN records. Follow operation results and PIN
+    reports when managing the records supported by a device.
+  type: object
+  properties:
+    supportedKinds:
+      type: array
+      uniqueItems: true
+      items:
+        type: string
+        enum:
+          - PERMANENT
+          - TEMPORARY
+    minLength:
+      type: integer
+      minimum: 0
+    maxLength:
+      type: integer
+      minimum: 0
+    pattern:
+      type: string
+      description: Explicit device PIN regular expression; absent means no character restriction.
+  additionalProperties: false
+authorization:
+  configuration: endpoint:read
+  attributes: endpoint:read
+  inboundMessages: message:send
+  resourcePermissionRequired: true