Description updates and local tests passed

stac-extensions · Jul 21, 2023 · 77ee542 · 77ee542
1 parent c7bd6e4
commit 77ee542
Show file tree

Hide file tree

Showing 3 changed files with 70 additions and 54 deletions.
diff --git a/.vscode b/.vscode
@@ -0,0 +1,5 @@
+  {
+     "editor.wordWrap": "wordWrapColumn",
+     "editor.wrappingIndent": "same",
+     "editor.wordWrapColumn": 150
+  }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated schema.json
 
 ### Changed
+- README.md updates
+- Updated secure asset item.json and collection.json to handle multiple authentification schemes
+- Updated schema.json for the updated security object structure
+
+- Updated README.md descriptions of the library
 
 ### Deprecated
 

diff --git a/README.md b/README.md
@@ -7,14 +7,13 @@
 - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Proposal
 - **Owner**: @jamesfisher-gis
 
-The Secure Assets extension to the [STAC](https://github.com/radiantearth/stac-spec) specification provides a standard way to specify if an asset 
-resides in secure storage. An alternative method (i.e. presigned URLs) would be required to access these assets. Presigned URL generation would 
-require calling out to an external API. The aim of the Secure Assets extension is to provide a standard field for clients to recognise secure assets
- and access them via the user's preferred method. 
+The Secure Assets extension to the [STAC](https://github.com/radiantearth/stac-spec) specification provides a way to specify what authentification 
+scheme is needed to access an asset in secured storage. The aim of the Secure Assets extension is to provide a standard field for clients to 
+recognise secure assets and access them via the specified authentification scheme.
 
-The Secure Assets extension is similar to the 
-[Alternative Assets extension](https://github.com/stac-extensions/alternate-assets/tree/main#alternate-asset-object) which aims to specify alternate 
-locations (e.g., URLs) for assets. Secure Assets aims to specify if an alternative dynamic method (presigned URLs) is needed.
+The Secure Assets extension aligns with the [stac-asset](https://github.com/stac-utils/stac-asset) which has support for several 
+[authentification clients](https://github.com/stac-utils/stac-asset#clients). A `SignedUrlClient` scheme may be specified that uses a custom API to 
+generate signed URLs. See the [Signed URL](#url-signing) section for an example Lambda function.
 
 - Examples:
   - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item
@@ -25,47 +24,49 @@ locations (e.g., URLs) for assets. Secure Assets aims to specify if an alternati
 ## Fields
 
 The fields in the table below can be used in these parts of STAC documents:
+
 - [ ] Catalogs
 - [ ] Collections
 - [ ] Item Properties (incl. Summaries in Collections)
 - [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
 - [ ] Links
 
-| Field Name           | Type                      | Description |
-| -------------------- | ------------------------- | ----------- |
-| security   | Map<string, [SecureAsset Object](#secure-asset-object)>  | Object that desribes the authenticated scheme and href |
+| Field Name | Type                                                    | Description                                            |
+| ---------- | ------------------------------------------------------- | ------------------------------------------------------ |
+| security   | Map<string, [SecureAsset Object](#secure-asset-object)> | Object that desribes the authenticated scheme and href |
 
 ### Additional Field Information
 
 #### security
 
 An Asset property used to specify a keyword that defines the security level of the Asset.The most common values may be "private" or "public".
- However, other keyword may be used to for alternative methods or levels of security.
+However, other keyword may be used to for alternative methods or levels of security.
 
 ### Secure Asset Object
 
 An Asset with the Secure Assets extension will have the following fields
 
-| Field Name  | Type   | Description |
-| ----------- | ------ | ----------- |
-| scheme           | string | **REQUIRED**. The authentification scheme used to access the data (`HttpClient` \| `S3Client` \| `PlanetaryComputerClient` \| `EarthdataClient` \| `SignedUrlClient`). |
-| description | string | Additional instructions for authentification |
+| Field Name  | Type   | Description                                                                                                                                                            |
+| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| scheme      | string | **REQUIRED**. The authentification scheme used to access the data (`HttpClient` \| `S3Client` \| `PlanetaryComputerClient` \| `EarthdataClient` \| `SignedUrlClient`). |
+| description | string | Additional instructions for authentification                                                                                                                           |
 
 ### Schemes
 
 The authentification schemes align with the relevant clients included in the [stac-asset](https://github.com/stac-utils/stac-asset) library.
 
-| Name | Description
-| -- | -- |
-| `HttpClient` | Simple HTTP client without any authentication |
-| `S3Client` | Simple S3 client 
-| `PlanetaryComputerClient` | Signs URLs with the [Planetary Computer Authentication API](https://planetarycomputer.microsoft.com/docs/reference/sas/) 
-| `EarthdataClient` | Uses a token-based authentication to download data, from _some_ Earthdata providers, e.g. DAACs
-| `SignedUrlClient` | Signs URLs with a user-defined Authentification API
+| Name                      | Description                                                                                                              |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `HttpClient`              | Simple HTTP client without any authentication                                                                            |
+| `S3Client`                | Simple S3 client                                                                                                         |
+| `PlanetaryComputerClient` | Signs URLs with the [Planetary Computer Authentication API](https://planetarycomputer.microsoft.com/docs/reference/sas/) |
+| `EarthdataClient`         | Uses a token-based authentication to download data, from _some_ Earthdata providers, e.g. DAACs                          |
+| `SignedUrlClient`         | Signs URLs with a user-defined Authentification API                                                                      |
 
 ### URL Signing
 
-The `SignedUrlClient` scheme indicates that authentification will be handled by an API which generates and returns a signed URL. For example, a signed URL for assets in AWS S3 can be generated with the following Lambda function code.
+The `SignedUrlClient` scheme indicates that authentification will be handled by an API which generates and returns a signed URL. For example, 
+a signed URL for assets in AWS S3 can be generated with the following Lambda function code.
 
 ```python
   import boto3
@@ -94,7 +95,7 @@ The `SignedUrlClient` scheme indicates that authentification will be handled by
               Params = {"Bucket": bucketName, "Key":key},
               ExpiresIn = 360
               )
-          
+
           return ({
               "statusCode": 200,
               "body": json.dumps({
@@ -104,7 +105,7 @@ The `SignedUrlClient` scheme indicates that authentification will be handled by
                   "Access-Control-Allow-Origin": "*",
                   "Access-Control-Allow-Headers": "*"
               }
-              
+
           })
       except Exception as e:
           return {
@@ -114,41 +115,43 @@ The `SignedUrlClient` scheme indicates that authentification will be handled by
                   })
           }
 ```
+
 Where the response looks like
 
 ```json
-  {
-    "signed_url": "https://<bucket>.s3.<region>.amazonaws.com/<key>?AWSAccessKeyId=<aws access key>&Signature=<signature>&x-amz-security-token=<auth token>&Expires=<epoch expiration time>"
-  }
+{
+  "signed_url": "https://<bucket>.s3.<region>.amazonaws.com/<key>?AWSAccessKeyId=<aws access key>&Signature=<signature>&x-amz-security-token=<auth token>&Expires=<epoch expiration time>"
+}
 ```
 
-The authentication API can be called clientside using an AWS S3 href (`https://<bucket>.s3.<region>.amazonaws.com/<key>`) with the following code snippet.
+The authentication API can be called clientside using an AWS S3 href (`https://<bucket>.s3.<region>.amazonaws.com/<key>`) with the following code 
+snippet.
 
 ```javascript
-  let signed_url
-  const auth_api = "";
-
-  function createSignedRequestBody(href) {
-    const bucket = href.split(".")[0].split("//")[1];
-    const key = href.split("/").slice(3).join("/").replace(/\+/g, " ");
-    return {
-      method: "POST",
-      headers: {
-        Accept: "application/json",
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ bucket: bucket, key: key }),
-      redirect: "follow",
-    };
+let signed_url;
+const auth_api = "";
+
+function createSignedRequestBody(href) {
+  const bucket = href.split(".")[0].split("//")[1];
+  const key = href.split("/").slice(3).join("/").replace(/\+/g, " ");
+  return {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ bucket: bucket, key: key }),
+    redirect: "follow",
   };
-
-  Promise(
-    fetch(auth_api, createSignedRequestBody(href))
-      .then((resp) => resp.json())
-      .then((respJson) => {
-        signed_url = respJson.signed_url;
-      })
-  );
+}
+
+Promise(
+  fetch(auth_api, createSignedRequestBody(href))
+    .then((resp) => resp.json())
+    .then((respJson) => {
+      signed_url = respJson.signed_url;
+    })
+);
 ```
 
 ## Contributing
@@ -161,23 +164,26 @@ for running tests are copied here for convenience.
 
 ### Running tests
 
-The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. 
+The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid.
 To run tests locally, you'll need `npm`, which is a standard part of any [node.js installation](https://nodejs.org/en/download/).
 
-First you'll need to install everything with npm once. Just navigate to the root of this repository and on 
+First you'll need to install everything with npm once. Just navigate to the root of this repository and on
 your command line run:
+
 ```bash
 npm install
 ```
 
 Then to check markdown formatting and test the examples against the JSON schema, you can run:
+
 ```bash
 npm test
 ```
 
 This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.
 
 If the tests reveal formatting problems with the examples, you can fix them with:
+
 ```bash
 npm run format-examples
 ```