posix mapper api

PM/openapi.yaml

@@ -0,0 +1,24 @@
+openapi: 3.1.0
+info:
+  title: POSIX Mapper API
+  version: "1.0"
+  description: |
+    The posix mapper API to discover local posix details
+    for users and groups
+servers:
+- url: /example
+
+tags:
+    - name: VOSI Capabilities
+    - name: POSIX Users
+    - name: POSIX Groups
+
+paths:
+    /usermap:
+        $ref: ./openapi/pm/posix-usermap.yaml
+
+    /groupmap:
+        $ref: ./openapi/pm/posix-groupmap.yaml
+
+    /capabilities:
+        $ref: ./openapi/vosi/vosi-capabilities.yaml

PM/openapi/pm/posix-groupmap.yaml

@@ -0,0 +1,107 @@
+get:
+  operationId: get-groupmap
+  tags:
+    - POSIX Groups
+  summary: get local posix info for groups
+  parameters:
+    - name: group
+      in: query
+      description: request only specified group records
+      required: false
+      schema:
+        type: array
+        items:
+          type: string
+        example: 
+            - "ivo://foo.net/gms?group1"
+            - "ivo://foo.net/gms?group2"
+            - "ivo://bar.net/gms?group1"
+    - name: gid
+      in: query
+      description: request group record(s) by posix gid
+      schema:
+        type: array
+        items:
+          type: integer
+        example:
+          - 10001
+          - 10002
+          - 20001
+          - 20002
+  responses:
+    '200':
+      $ref: '#/components/schemas/posix-groups'
+    '401':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated
+    '403':
+      $ref: ../vosi/vosi-std-responses.yaml#/permission-denied
+    '404':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-found
+post:
+  operationId: create-groupmap-entry
+  tags:
+    - POSIX Groups
+  summary: create a local posix info for a group
+  parameters:
+    - name: group
+      in: query
+      description: |
+        create and return a posix group entry for the specified group;
+        the value is an IVOA Group URI as defined by the GMS standard
+      required: false
+      schema:
+        type: string
+        example: "ivo://foo.net/gms?group1"
+  responses:
+    '201':
+      $ref: '#/components/schemas/posix-groups'
+    '401':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated
+    '403':
+      $ref: ../vosi/vosi-std-responses.yaml#/permission-denied
+    '404':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-found
+    '405':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-implemented
+
+components:
+  schemas:
+    posix-groups:
+      description: list of groups with posix details
+      content:
+        text/plain:
+          description: posix groups in /etc/group format
+          schema:
+            type: string
+            examples: 
+              - "foo_group1:x:20001:"
+              - "foo_group2:x:20002"
+              - "bar_group1:x:20003"
+        application/x-posix-group+json:
+          description: 
+          schema:
+            type: string
+            example: |
+              [
+                {
+                  "uri": "ivo://foo.net/gms?group1"
+                  "posix": {
+                    "name": "foo_group1",
+                    "gid": 20001
+                  }
+                },
+                {
+                  "uri": "ivo://foo.net/gms?group2"
+                  "posix": {
+                    "name": "foo_group2",
+                    "gid": 20002
+                  }
+                },
+                {
+                  "uri": "ivo://bar.net/gms?group1"
+                  "posix": {
+                    "name": "bar_group1",
+                    "gid": 20003
+                  }
+                },
+              ]

PM/openapi/pm/posix-usermap.yaml

@@ -0,0 +1,106 @@
+get:
+  operationId: get-usermap
+  tags:
+    - POSIX Users
+  summary: get local posix info for users
+  parameters:
+    - name: user
+      in: query
+      description: request user records by identity
+      required: false
+      schema:
+        type: array
+        items:
+          type: string
+        example: 
+          - "https://idp.example.net/ 2273b75c-33fd-4606-8119-37ed4909ba36"
+          - "https://idp.example.net/ d37a9f17-e1ae-4fe4-ae93-9fd6b42b2a79"
+    - name: uid
+      in: query
+      description: request user record(s) by posix uid
+      schema:
+        type: array
+        items:
+          type: integer
+        example:
+          - 10001
+          - 10002
+  responses:
+    '200':
+      $ref: '#/components/schemas/posix-users'
+    '401':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated
+    '403':
+      $ref: ../vosi/vosi-std-responses.yaml#/permission-denied
+    '404':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-found
+post:
+  operationId: create-usermap-entry
+  tags:
+    - POSIX Users
+  summary: create a local posix info for a user
+  parameters:
+    - name: user
+      in: query
+      description: |
+        create and return a posix user entry for the specified user; the value is
+        a string representation of the identity and details depend on the identity
+        type(s) in use
+      required: false
+      schema:
+        type: string
+        example: "https://idp.example.net/ 2273b75c-33fd-4606-8119-37ed4909ba36"
+  responses:
+    '201':
+      $ref: '#/components/schemas/posix-users'
+    '401':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated
+    '403':
+      $ref: ../vosi/vosi-std-responses.yaml#/permission-denied
+    '404':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-found
+    '405':
+      $ref: ../vosi/vosi-std-responses.yaml#/not-implemented
+
+components:
+  schemas:
+    posix-users:
+      description: list of users with posix details
+      content:
+        text/plain:
+          description: posix users in /etc/passwd format
+          schema:
+            type: string
+            example: "someone:x:10001:10001::/home/someone:/bin/bash"
+        application/x-posix-user+json:
+          schema:
+            type: string
+            example: |
+              [
+                {
+                  "identity": "https://issuer.example.net/ 71f59b77-e71d-4cbb-9f7f-f8bfecdc3783"
+                  "posix": {
+                    "username": "someone",
+                    "uid": 10001,
+                    "home": "/home/someone",
+                    "shell": "/bin/bash",
+                    "group": {
+                      "name": "someone",
+                      "gid": 10001
+                    }
+                  }
+                },
+                {
+                  "identity": "https://issuer.example.net/ 8f478279-c148-46b3-8784-efd0ee5db242"
+                  "posix": {
+                    "username": "someone_else",
+                    "uid": 10002,
+                    "home": "/home/someone_else",
+                    "shell": "/bin/bash",
+                    "group": {
+                      "name": "someone_else",
+                      "gid": 10001
+                    }
+                  }
+                }
+              ]

PM/posix-details.puml

@@ -0,0 +1,70 @@
+@startuml
+
+top to bottom direction
+
+class PosixUser {
+  - username: String
+  - uid : Integer
+  - home : String
+  - shell : String
+  - group : PosixGroup
+}
+PosixUser -l[hidden]-> User
+note right of PosixUser
+  username is locally unique
+  uid is locally unique
+
+  Minimum surprise/friction for primary group:
+  PosixUser.username == PosixGroup.name
+  PosixUser.uid == PosixGroup.gid
+  (but this is not required)
+end note
+
+class PosixGroup {
+  - name : String
+  - gid : Integer
+}
+PosixGroup -l[hidden]-> Group
+note right of PosixGroup
+  name is locally unique
+  gid is locally unique
+end note
+
+class User {
+  - identity : Identity
+  - posix: PosixUser
+}
+note left of User
+  identity is globally unique, such as:
+  OpenID {issuer} + {sub}
+  X509 distinguished name
+  etc
+end note
+
+class ManagedUser {
+  - username : String
+  - emailAddress : String
+  - firstName : String
+  - lastName : String
+}
+User <|-- ManagedUser
+
+class Group {
+  - uri : URI
+  - posix: PosixGroup
+}
+Group -u[hidden]-> ManagedUser
+note left of Group
+  uri is globally unique: IVOA Group URI
+end note
+
+class ManagedGroup {
+  - owner : ManagedUser
+  - description [0..1]: String
+  - members [0..*]: ManagedUser
+  - memberGroups [0..*]: ManagedGroup
+  - admins : TODO
+}
+Group <|-- ManagedGroup
+
+@enduml

PM/rsync-openapi-components.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+DEST=openapi/
+VOSI=$HOME/work/dev/ivoa-std/VOSI.git
+
+ARGS="$1 -avc --delete"
+
+rsync $ARGS $VOSI/openapi/vosi openapi/
+